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
I want to make a technical documentation of an existing web site for developers so that new developers can continue to work with it. In existing codes, little (or not at all) in-code comments or doc-strings are available (bad practice, I know). Yeah, I have seen some posts related to these. But those were not that detailed. Here are all my questions:
What to include?
How to organize? I mean, can you suggest some hierarchy so that new developers can easily get onto the track?
What are the best practices?
Can you show some samples?
How can it be made easy? Some ppl suggests wiki tool but I know nothing about it, will it be useful? Can you suggest any tool with some quick starting tutorial?
I have never made one. So I appreciate any kind of answer. Thanks in advance.
(Links will be helpful but please give a quick and lucid summary of it)
Quick and lucid:
Think of it like any paper.
What is the goal of the app (website)? [why?]
How does it achieve this goal?
What problems have arisen?
What problems could arise?
What could be expanded upon? [why?]
What problems could expansion cause? [why?]
What naming/formatting conventions should continue to be followed?
Outline format is great.
In addition to Nona's suggestion I would also say that it is important to break down the code and explain any conventions and intentions of the code so that there is uniformity between developers for things like ID values, CSS classes, and JavaScript function names. Be as specific as you determine necessary to prevent a new person to the team from reinventing work.
If you're looking for a quick way to get through your code, try .NET Reflector. It gives you a broad overview of all your classes, methods, properties, etc. so that you can write all the technical documentation you need without actually going through the files. It's super easy to browse through and it will even show you the code itself.
Have you thought about representing what is there with some UML notation? That's what UML is for! If the new developers are good then they should be able to understand it.
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 3 years ago.
Improve this question
I'm a React Native Developer from the past 7 months. And this is my first technology I'm working on. So, I recently got to know that there are certain coding rules which I wasn't following and was unaware of. I have two general programming questions.
So I just got to know from an inteview that one should create wrapper functions in their code, by which I can just call a single function which points to a module or a API.
Like wrapper functions, what else is a good practice in programming?
Since I never worked on Android/iOS before and directly jumped to React Native. I often find myself doing trial and erros when it comes to do styling in my application.
Or what is the right way to style an element without giving too much margin/padding, which I assume is wrong. Or what is the right way to style where the styling works the same in all devices. Can someone recommend me a right article or video or something for this styling issue?
This may well be the broadest question(s) on StackOverflow :-). Just a few suggestions for the first question.
1. Read :
Many books have been written, some down-to-earth (Clean Code, The Pragmatic Programmer, Code Complete, Refactoring, ...), some more theoretical (Structure and Interpretation of Computer Programs, ...).
2. Collaborate :
You can sollicit code reviews from colleagues, have pair-programming sessions with them, attend coding dojos or hackathons. All of these are ways to share and transfer knowledge among peers, are very helpful, and almost always fun, too.
3. Play :
Sites like codewars.com are great to let you experiment with huge numbers of coding challenges, risk-free, and with the bonus benefit of seeing the solutions of others (once you're done :-)).
Maybe it's worth posting the second question separately, with the appropriate title. Good luck!
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
It sounds strange, but that's what I need. An effective way to document a Scrum project.
I agree that it's a waste of time to produce User Stories and a Requirements Documents.
But sometimes we need to have the vision of how the software currently works.
How do you do that? Do you know some best practices or case scenarios on this?
Thanks
The short answer is this: you can write anything you want or need to about any project, Scrum or otherwise. Scrum doesn't tell you how to document, but it doesn't tell you not to. The way you document is in itself irrelevant to Scrum.
That said, if you need to understand how the software currently works, a document will not help you. Documentation often lies. If you're trying to understand how the system works, a document will only tell you what people think or want to believe is the truth.
What you should consider, is to use executable specifications and Test Driven Development to prove that what you believe the software does is actually true. automated tests combine documentation, examples and regression tests all into one offer.
There are several kinds of documentation that can help you. It depends on your context which ones you need, and at what detail level. You could also use a tool such as MOOSE to create project specific visualizations of your software at all levels. Some simple documents are:
A story map
Gherkin style high-level features and scenarios
If you've tracked your product backlog items through completion, including acceptance criteria for each you should be able to point to the list of completed product backlog items as documentation. Everything you've programmed should be associated with a PBI, so the completed PBI's document your project.
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 6 years ago.
Improve this question
How to write a vision [generally] for some business ? Is it have some template ? any example ?
Business about online ticket services .
What is a 'vision'?
It's such a nebulous objective... I don't see how there could be a template. Unlike requirements specifications, functional specifications etc, there is no accepted understanding of what a 'vision' actually is...
I'd speak to the person who commissioned you to write the 'vision', and ask them what exactly they are trying to achieve and what their expectations are.
Here is a nice article on the Vision. Note that it doesn't have to be a heavyweight document (spend as little time as possible but as much as required). For more formal templates, RUP has some for the Vision artifact.
Karl Wiegers' book, Software Requirements, has an excellent template. I've used in for several projects. It seems a bit formulaic at first, but over the subsequent days and months, really helps a team keep focus.
http://www.amazon.com/exec/obidos/ASIN/0735618798/processimpact
http://www.processimpact.com/books.shtml
The Business Motivation Model is a great source. They define what a business vision is, relate this concept to other relevant concepts in the organisation, and give good examples.
If you are interested in how business requirements are refined into user requirements and how, eventually, they determine what a software system does, you may want to have a look at the OPEN/Metis white paper.
First i warn you : Do not be a template zombie...
Secondly to give you just an idea OpenUP has a nice -non commercial Vision Template...
Check my answer how you can get it : RUP (Rational Unified Process)
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
I am developing an application that can be extended using "plug-ins". The plug-ins will be pretty basic, allowing developers to add new "actions" to my application.
What documentation/information do I need to provide so that developers can do what they need to?
I was thinking a short example and a general overview of how the application/plug-ins work?
You need to foster a sense of community. Things like:
sample code for more than one real plugin;
a getting started guide for plugin writers;
details on how to deploy a plugin and on how they are discovered by your application;
a wiki so that plugin writers can collaborate, and
an easy way for plugin authors to contribute their plugin
might help.
You also have to decide how detailed your API is going to be. IF you are offering a rich API, make sure to document it well, and to explicitly highlight directives (explicit "do" or "don't do" instructions).
Most users will not bother to read the documentation and figure out things from the name, or skim your docs. So it is best if you can avoid "surprising them", and if not, at least offer them a chance to find the problems.
Finally, err on the side of caution with checking correct use and send exceptions rather than counting on users meeting your instructions.
Also, think very well in advance on whether you truly expect anyone to use your plug-ins because the core product becomes a "hit".
It is very common to err on the side of optimism, and think that when you are writing a plug-in infrastructure that somebody will actually use it.
However, nobody is likely to write plugins before the core out-of-the-box offering is successful and popular. You may be better off publishing and distributing your own plugins before worrying about extensions by others.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
Perhaps if I make the my documentation better I could spend less time supporting developers and more time developing myself:
I develop a critical platform used by 10 other developers and 50 end users. The developers are of mixed ability ranging from domain-experts to relative beginners. Since I'm one of the people who know how the core platform works support requests from other developers usually go via me.
Our documentation is the usual sort of descriptive stuff any mature project will have: We have a large wiki containing details of all the usual operating procedures plus extensive API documentation.
Unfortunately it does not cater well for "how do I fix " type questions:
Would it be possible to make some interactive fault diagnostic documentation that puts users through a standardized fault-finding routine. The documentation would ask users a series of questions, and depending on the user's input would tell them what to do... it would be a very simple expert system, or possibly a documentation state-machine.
The idea would be to help newbies think more methodically about diagnosing faults in this complex system.
My question:
Are there any free tools intended to implement this kind of user-experience? I'd rather not hand-roll this. There must be some kind of framework for interactive help & documentation.
Has anybody implemented this kind of system before?
If you just wanted to have a flowchart/stat-machine thing where the user moves from the start point to a set of possible solutions by answering questions, then you could probably implement this as a set of wiki pages, where the possible responses to questions on one page are links to other pages.
This solution relies on being able to represent the answers to questions as links, which isn't going to work if the information is more form-like. For example, suppose one question is "What brand of graphics card do you have?" where the answer is one of 300 possible options. In this case it's going to be tiresome to create the links :)
If the developers are asking too many questions then I would suggest making them research the question themselves and come up with an answer, then double-check with you instead of encouraging them to ask you every time. It's much easier to ask somebody else than to find the answer yourself, but they're never going to learn if they don't look for themselves.
If the users are asking a lot of questions then you may need some user interface improvements. Try putting hints in the application itself at the top or bottom of the screen maybe.
For both groups of users a wiki can help.
a FAQ in your wiki
if an error happens too often, try preventing it or output a more useful error message (like "if this happens, the likely cause is that...)