Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
This question does not appear to be about programming within the scope defined in the help center.
Closed 5 years ago.
Improve this question
Of all the annoying buzzwords, "functionality" is the worst when I am in the middle of writing a specification (as I am now): "these requirements define the functionality to be included in version 2"..."as part of the download functionality, we need to capture blah blah blah" (Don't get me started on "capture")
"Functionality" is too cumbersome, and makes it sound like you are trying to make something sound more important than it is. "Capability" works sometimes, and sometimes "function" itself works; "subsystem" might work at times too...but we need a simple word for the concept of "set of related functions", preferably in 3 syllables or less. Any suggestions?
Features.
How about that? Simple, to the point, not spin.
How about:
The user manager page is where all of the user management functionality love nuggets reside.
or what about:
The portal features a budgeting subsystem, wherein all of the budgeting functionality goodie gum drops can be derived.
or even:
By clicking on the submit button, you'll be showered with all of the wonderful functionality hot mommies that one could hope for.
These have all worked well for me when specifying the functionality that will be in my new projects. YMMV...
Ooh, this is a tricky one. For smaller items I often use the very buzz-wordy "widget", which works pretty well for self-encapsulated systems.
"Functions" as a plural also works in some contexts - as can "actions" (as in 'the application needs to be able to perform the following actions...').
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I have looked at many articles regarding REST and its design implementation for an API. I have a couple of questions however, and maybe they are simply opinionated as there is no "one fits all solution" to REST or API development in general.
Note that these questions are in regards to contacting and receiving requests from an SDK.
My questions are both in regards to the URI form, as I believe it is called. I have seen this represented in a few ways, but my big concern is about versioning and "dynamic" sections.
For my first question (version'ing) I have seen the following approached used often.
/customers/accounts/V3.4/customer_id/1234
/customers/accounts/V3.5/customer_id/1234
Developers would implement this by keeping a general version class, and as they make calls it would grab whatever version the developer has setup. So if they ever wanted to move up to a new API version they would just have to modify the V#.# in one location. I am wondering how good of an this idea is in practice, especially for an SDK. My general thoughts are that this is OK. I believe this as versions are clearly pointed out. If a change needs to be made it is simply a matter of updating your version's call. With an SDK in mind, using an old API won't break anything as if they do not update for awhile then their API request will still be fine, but will route through an older endpoint.
Question 1. Is version'ing using the approach above okay for API updates? Pro's/Cons?
The second question about dynamic values can be seen as follows.
/customers/V4.3/{customer_id}/account
versus
/customers/accounts/V3.4/customer_id/1234
I am not sure if there is a better trade-off to having dynamic endpoints versus hard coding them as listed above. I say this because what if we have a scenario where we wish to add details to the "account" page.
In the above example customers/V4.3 would not have to be updated, as it still contains the same user list midpoint. We would be able to update the account API without causing a version change. (forgive me if that is a terrible idea). But with the second option we would have to update the versioning as that is a midpoint
Question 2. In the example above, is it better to focus on more static or dynamic endpoints?
Still very new to learning about this, forgive me if I made some bad assumptions or conclusions on API design.
What is the problem with using Parameters ?
IMHO
Things that are dynamic or can change in future should never be part of the URL path.
This is why parameters exists. And the benefit is :-
http://example.com/api/resource/?customer_id=1234&v=3.4
Would be treated the same by your script as:-
http://example.com/api/resource/?v=3.4&customer_id=1234
I don't know the context of the SDK, but I would think hard about requirements before allowing API users to choose the version & perform actions.
Also please take a look https://stackoverflow.com/a/17999251/2489860
This is one of those RESTful debates that can go round in circles. You have three options for specifying the version: the URL, the content type or a custom header. All of them will be considered "wrong" by some folks.
Troy Hunt's written a pretty good discussion around the pros and cons here:
http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
However, I wouldn't necessarily be too quick to reach for versioning as a solution. You may want to consider side-stepping the issue by using more tolerant consumers, investing in more up-front design or applying the open/closed principle to your APIs.
This argument is expressed in more detail here:
http://martinfowler.com/articles/enterpriseREST.html#versioning
It includes a great quote:
"Some people, when confronted with a problem, think "I know, I'll use versioning." Now they have 2.1.0 problems."
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Currently I am working on porting a benchmark application to another system. I am working alone, so I am frustrated about which software methodology I really have to use. Please give me some ideas.
I am going to assume you're wondering which Agile approach to use on your project as you tagged your question accordingly.
Agile is mainly about:
Delivering working software continuously and regularly
Aiming at technical excellence and avoiding technical debt
Improving the way we work and retrospecting regularly
I'd say whatever you use, even your very own approach to software development, if you can check those three items from the list, then you're pretty much Agile to me. Some people need strict guidelines and artifacts and that's fine, they help people become Agile but are far from being mandatory despite the dogmas out there.
Here's how I would approach your situation.
Take a step back and try to identify the most important features or abilities of this benchmarking application. By most important, I mean those features that the people using it in the end cannot live without. Once you have a list of those, put them on post-it notes, index cards, trello, jira or whatever tool you want to use.
Split each of those features into full-stack chunks of functionality that are business driven. I'm not talking about technical tasks here, but smaller features usable by actual people. I usually opt for the "Grandma Driven" approach here, asking myself "would grandma be able to understand what I'm trying to do?". It's just to make sure I'm focusing on a full stack feature and not a technical task like "populate database". One way to see this is also by applying dimensional planning to each of the features you identified (http://www.xpday.net/Xpday2007/session/DimensionalPlanning.html).
Set yourself an iteration length (I usually go for 1 or max 2 weeks when I'm working alone) and get to work one small item at a time. Don't write code for later, only what you need to solve the problem at hand. Quality is not an option. Focus on good coding and testing practices.
At the end of your iteration, check how many features you implemented and put that number somewhere on a chart, in a google spreadsheet or whatever. This will help you see if you're on track. Get feedback from colleagues or any potential users of the system and reflect on that feedback. It's not because you're porting to another platform that you can't make it better.
If you end up not having small enough granularity with what's left or not enough stuff in your list of things to do, spend some time repeating steps 1 to 3.
At the end of each iteration, keep tracking how many items you did just to see if you still have a good enough pace. If not, ask yourself why and change something in the way you work or get help. Again, your main focus is to make progress and deliver software that works at the end of each iteration.
It might not answer your question and I know I didn't give you an answer of the type, use kanban, scrum or whatever but I truly believe it's not appropriate in your specific case and would only generate overhead and boredom for you.
Hope that helps anyway, good luck with your project.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I'm starting project number 8,192. Like most of my projects, they are either throw-away projects or projects that get canceled either from boredom, time or lack of usefulness.
But there is a project that has been on the back-burners for a long time that I really want to finish. In my perfect world mind, it should take 3 months for first release.
Anyway, one of my biggest issues is taking a large project (or even a small to medium one) and break it down into manageable pieces. My error is to always jump right on the terminal, open Textmate and start coding. This almost always fails. I get lost in feature creep, learning newer methods, framework wars, etc. Then, two months have gone by and nothing to show for it.
So I was thinking if BDD (such as Cucumber) might be a solution to this? Could it be used to scope out the larger pieces, then the smaller pieces until I have a feature list that is most of the project. At that point, I just start coding the pieces right?
What are your suggestions on tackling this problem that I'm sure other developers share.
BTW, I'm using Rails 3 (sometimes Padrino).
Thanks
On which track? BDD doesn't define the track--it communicates the track.
BDD may be the only requirements you have (or need), but that doesn't address the issue of feeping creaturisms unless you have the discipline not to implement anything for which no spec exists.
Uncaptured features don't get implemented, period. If a feature is added, it gets a scope, and is prioritized with the rest of the features. It may usurp something less-desirable, it may not.
The product owner (you in this case) must decide how much can be implemented in the time allotted, and which features should be implemented. Still boils down to discipline, however, you just have a tool that (helps) make sure what you implemented is what you actually wanted.
It doesn't, however, make sure that what you get is only what you originally wanted--it won't make sure nothing else is implemented on top of the specs you bothered to implement.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
As the years go by we get more and more applications. Figuring out if one application is using a feature from another application can be hard. If we change something in application A, will something in application B break?
We have been using MediaWiki for documentation, but it's hard to keep the data up-to-date.
I think what we need is some kind of visual map of everything. And the possibility to create some sort of reference integrity? Any ideas?
I'm in the same boat and still trying to sell my peers on Enterprise Architect, a CASE tool. It's a round trip tool - code to diagrams to code is possible. It's a UML centric too - although it also supports other methods of notation that I'm unfamiliar with...
Here are some things to consider when selecting a tool for documenting designs (be they inter-system communication, or just designing the internals of a single app):
Usability of the tool. That is, how easy is it to not only create, but also maintain the data you're interested in.
Familiarity with the notation.
A. The notation, such as UML, must be one your staff understands. If you try using a UML tool with a few people understanding how to use it properly you will get a big ball of confusion as some people document things incorrectly, and someone who understands what the UML says to implement either spots the error, or goes ahead and implements the erroneously documented item. Conversely more sophisticated notations used by the adept will confound the uninitiated.
B. Documentation isn't/shouldn't be created only for the documenters exclusive use. So those who will be reading the documentation must understand what they're reading. So getting a tool with flexible output options is always a good choice.
Cost. There are far more advanced tools than Enterprise Architect. My reasoning for using this one tool is that due to lack of UML familiarity and high pressure schedules, leaves little room to educate myself or my peers beyond using basic structure diagrams. This tool easily facilitates such a use and is more stable than say StarUML. (I tried both, StarUML died on the reverse engineering of masses of code -- millions of lines) For small projects I found StarUML adequate for home use, up until I got vista installed. Being opensource, it's also free.
With all that said, you will always have to document what uses what, that means maintaining the documentation! That task is one few companies see the value in despite its obvious value to those who get to do it. . .
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.