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 work for a insurance company. We have our own development department made-up of almost 150 people plus some providers (outsourcing and custom made apps pretty much). In our company my team have made what we call non-functional logic libraries. That is, software libraries to handle things that are horizontal to all the development teams in our department, e.g. Security, Webservices, Logging, Messaging and so on. Most or these tools are either made from scratch or adaptation of a de-facto standard. For example our logger is an appender based on Log4J that also saves the logging messages into a DB. We also define what libraries to use in the application, for example which framework for webservices to use. We use pretty much JavaEE and Oracle AS in all our organization (with some Websphere Application servers).
Much of these projects have their architecture documented (use cases, UML diagrams, etc) and generally the generated documentation are available.
Now what we have seen is that for users sometimes is difficult to use the the libraries we provide and the are constantly asking question or they simply don't use them.
So we are planning to generate a more friendly documentation for them, so my question is:
What are the best practices or the checklist that software documentation should have?
Something comes to my mind:
API Reference guide
Quick start Tutorial
API Generated Documentation.
Must be searchable
Web Access
What else should it have? Also, based in your experience what is the best way to maintain (keep it up-to-date) and publish this type of documentation?
Keep your documentation in version control too.
Make sure on every page it has a version number so you know where your user has been reading from.
Get a CI server going and push documentation to a LIVE documentation site upon updates.
Do documentation reviews like you would code reviews.
Dog-food it :)
Kindness,
Dan
Related
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
My team and I are currently building multiple services in parallel. We have the benefit of building all the services from scratch. I would like the ability to automatically display all API endpoints, from all services, in one page/site. This would be helpful because (among other things):
I don't have to go to multiple documentation sites to see what are the available endpoints in my entire "system".
It'll be a good first step to determine if any of the services should be split, combined or simply refactored.
Some of our services are in Django and the rest-swagger module is a great help. But I don't see how I can combine rest-swagger documentation from multiple services into a single documentation page/site.
I'm currently looking through this site and anything related to the Netflix experience but could not find a solution to my problem. Maybe centralized documentation isn't a big deal with 600+ services at Netflix, but that's hard to believe.
Can anyone suggest a tool or method to have a combined API documentation for all services in a microservice architecture?
My ideal scenario of what happens when a service is changed:
I click on the link to see the list of endpoints in my system.
A teammate updates a service and also it's documentation.
I refresh the page I am currently and I see that change made from step #2.
With my exp, you have some paths.
http://readme.io/
Make a wiki with JIRA, Redmine.
In Github create a repo for exclusive docs.
Google Docs.
I don't know about any existing tool rather I'm just putting my thought on where to do it.
From what the OP describe, they are already building a micro services architecture using Netflix stack. There should be a repository to config the name (or URL) for each of the services and the 'config server' or 'service registry' will read from that. To me, that's the perfect place to put the reference to each of the micro-service's documentation under their own entries. This way you get the benefit of maintaining the documentation and code at same place, plus you could potentially also collect run time information like instance/connections count if you hook into the config/registry server.
Being in similar situation I am looking to adopt https://readthedocs.org/ with GIT backed.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
Gathering requirements is an essential stage creating software or web applications.
I have searched the web extensively without finding any directions on how to elicit requirements for personal projects. All information i found - including books i read - is focussing on different stakeholders.
So i´m wondering, what would be the best way to 'gather' the requirements for personal projects?
I can't imagine i'm the only one with this question. I have plenty of ideas for webapplications. Since i am the only stakeholder at this time - no users are identified yet, i need to develop a couple of applications for personal use - i find it hard to interview my self to elicit those requirements.
As English is not my native language, apologies for possible textual errors.
You can have a document with all the information you have in your head of the project in a bullet list format called "Project Memoir". Just list all the information & business rules you need to put in the project. You can after that start developing a kind of informal Software
requirements document (as it's for a personal project) containing some essential information for you in the development phase, like a feature list with their description, use cases & scenarios that will help you in testing in later phase, mock up screens for defining the UI look & elements, data elements lists for defining screen contents. Just keep it simple & easy as it's for only your personal use.
Hope that would help :)
The questions are supposed to be a trigger of a thought process.
What makes it any different in case you are the developer next to the stakeholder? Your thoughts are those of a stakeholder and you will have to try to identify your own requirements by this process.
Identifying your own requirements with a structured approach will help you identifying requirements that you would otherwise have encountered during development.
If the sole purpose is not only personal, I doubt whether it is a good idea to start developing. Then you will need to find prospects to interview. Investigate the possible markets.
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 7 years ago.
Improve this question
Can anyone give advice, or point to any guides, on how to manage a community of open source software developers in writing api documentation?
A typical, unmanaged, starting point for most projects is to have a project wiki where anyone can freely create pages, add content to existing pages, edit existing content etc. The problem is that, despite people's best intentions, the wiki can easily end up being a disorganised, poorly written, incomplete, written in disparate voices etc etc.
So, what to do to improve the quality of the documentation?
I suspect a key ingredient is clear editorial/style guidelines, something similar to http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone. Can anyone point to an example of such a guide tailored specifically to software apis?
Are there any other practices that people have found useful? E.g. form a core team of editors and accept that most documentation that gets added by the community will most likely need to be 'strongly edited'?
The short answer, that the solution is social/human and not technical. The way to get good documentation for any project is to have someone with time, in charge of doing high level organization for the documentation, and then being involved in the development and user communities to ensure that the documentation remains up to date and continues to address the problems and confusions that users typically have.
Community projects have accepted that you need point people (i.e. "managers," for aspects of the project like "translation," and "release," and for various components. The same thing needs to happen for documentation.
As for tools, Sphinx is really great though it's not "wiki like," exactly you can use whatever version control system your project is comfortable with to store documentation and configure your web server to rebuild the documentation following commits/updates/pushes. Which has always worked just fine for any project I've worked on/with.
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
I inherited an old app, written in C#/.NET 2.0. (un)Luckily there was no documentation - not even comments. So as I'm adding enhancements to the application based on new requirements I'm also building a mental model of what the app does and how it does it - architecture in other words.
I was wondering what tools exist out there to "deconstruct" the app and go from raw code to something higher level? The app's not really heavy in OO - in fact one of the objects used is called a "function". It's mostly just a bunch of methods - a lot methods that seem to jump out of nowhere.
I want to translate the raw code to some sort of requirements doc stating what the app does and how it executes. What's the best way to do it? Are there any apps out there that can help me? Maybe templates of what I should/should not include? Maybe books/sites that you recommend? The goal is to provide documentation for me and for future developers maintaining the app.
Personally, I would start with Robert C Martin's Agile book, and Eric Evan's book on Domain Driven Design. Those are theory books, but Uncle Bob's book specifically talks about revamping code to be manageable, just like your situation.
It's pretty essential to layer your software so you can start to remove dependencies, which will make everything very simple and easy to maintain.
I am a database guy, so I started with a good ORM like Entity Framework or Fluent NHibernate. I prefer websites, so I went with ASP.NET's MVC 2, then started writing all the parts of those books, namely a data Repository, Services to pull data and Control to push it. MVC is a very nice separation of data concerns and "View" concerns which are your screens. Before long, you would have very clean and easily maintained software.
If you are using VS 2010, you can see a menu with the name: Architecture. Using this tool, you can create a dependency graph of your application, you can use it as described in the following:
Link
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.