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 going to be taking over from a developer here at work soon. Hence, I'll be supporting all the applications that he has written over the last few years.
My question is, when supporting an application that you probably don't know much about, what kind of documentation is most helpful to get a handle on how to fix problems, extend functionality, modify functionality, etc? I'm thinking it would need to give you an overview of what the software does, what interfaces it has to other software, what databases it uses, usernames, passwords, and so on.
Is there such a thing as a software support document? Referrals to any templates would be most helpful.
BTW, unfortunately, there are no requirements documents, specs, etc! So, really my question is, if my colleague had a day to write a single document for each application so that I could (more easily) support it, what would that document be and/or what would it look like?
I would ask for primarily some sort of flow chart/schema of the way the app functions.
I would want to be able to know how each file interacts with other files (and the database). So this way, you'd know where to start to fix a bug or add a new feature, etc.
So to do a quick, text mockup of it:
Index.php -> Login.php -> Dashboard.php
Index.php:
Has login box. Submits login into to login.php
Login.php:
Verifies data with database entries, shows error on fail or sends to Dashboard.php
Dashboard.php:
Once logged in this acts as a main menu
Something along these lines? For basic documentation I'd think this is the way to go.
Hope this helps. Good luck!
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 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 7 years ago.
Improve this question
First and foremost, I would like to say I am very, /very/ new to programming and the like. If I decide to build this, this would probably be my first "large" project i've ever done myself.
What I am looking to build is a very simple Chat/IM client to use for the users in our office network. It would just call us their Windows logon name and use that to IM and the like. I'm talking a very simple client, with a list of names of people who are logged into the network, and option to IM them and an option to do a multiple user chat. It doesn't have to be visually stunning.
How difficult would this honestly be? Is it possible for me, someone who has very little knowledge when it comes to programming to teach myself how to build it?
If not, can you explain why this would be very difficult and what already built clients would work well for what I am using?
This is a big application. Your first parts will suck and refactoring it later will suck even more. I suggest building something small in the first place and then step from one bigger project to another.
XMPP/Jabber is IMHO the best solution for office IM. Most clients like Pidgin, Adium etc can connect to it. Every bigger company I worked for in the last years used it. Take a look at Openfire - A free open source XMPP server that you can directly connect on and which is easy to set up: http://www.igniterealtime.org/projects/openfire/
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
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'm working on quite complicated project, in terms of business-logic quantity and quantity of components.
Each developer mostly works on "his own" component. I understand that this isn't very cross-functional, but it is impossible to know every components' details.
Team sostav changes from time to time. So we have situations when one person have to work on "other person's component". And this can be on periodic basement, so you can come back to the issue a month later - in that moments you can ask component business-logic's owner the same questions again and again, because you simply can forget some tiny but important details a month later.
This situation is annoying sometimes.
We have daily stand-up meetings, when person tells about what he has done and going to do.
We have project's wiki F.A.Q. page - we extract the most frequently asked questions.
What do you think about the problem?
And how would you recommend us to solve it?
given the component nature I'd go with:
1.) A framework document specifying the applications purpose, setup, requirements etc.
2.) Module documents for each component in a common format and indexed by name.
Look at the http://docs.python.org for a good example of general docs and http://docs.python.org/modindex.html for a good example of module/component docs
Oh, and daily meetings are generally bad, they take up a lot of time and answers get forgotten. Newcomers or sick people miss the meetings and have to be re-briefed. It's 100x better to write it all down and keep a paper/email trail unless discussion/feedback is required.
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.