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
Just to be clear, I'm not asking how to add dependencies in a README.md, but rather, how to handle documenting them given my situation.
Looking at the SO Help Center, I saw this as "a practical, answerable problem that is unique to software development," and I thought it appropriate to ask here.
I need some guidance on a project. To summarize... The project is a technology prototype for a small business, which I'll call "ACME," which contracted with me, and is using Raspberry Pis as a distributed client network to provide a service to their customers. The ACME's owner is not technical. He emphasized simplicity, extensibility, and stability for the project, and I want to avoid unnecessary confusion.
Where I'm becoming concerned is that while my direct dependencies are few, about two or three, my sub-dependencies are numerous. (To clarify, I'm coding the project in Node.js, with the exception of a few small C++ worker programs.) The modules I'm working with collectively sum up to about 40 sub-dependencies or greater.
The most important thing to me is to do the right thing, especially with this being my first official job as a developer, and I'm all on my own with no senior developer to advise.
So... should I only list my direct dependencies (which I would prefer, and which handle documenting their dependences themselves), or list all dependencies?
npm can list your dependencies just fine by itself (npm ls). What you need to document is how to get the system up and running, both as a user and as a developer (your successor or yourself in the future when you need to restore your dev setup from scratch).
EDIT: Additionally you will want to document how your own programs fit together as components in the whole system.
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 4 years ago.
Improve this question
Rakudo Star is a release targeted towards end users (if I'm not mistaken). As such, it includes a number of useful modules that can be used in a wide range of projects.
But how does the team behind it decide which modules to include? Do module developers talk to them and ask for inclusion, or do they look at usage statistics and include the most popular? Or is inclusion completely arbitrary?
What process should one go through to get their module included?
The collection of modules is in the star repository, includes as sub-modules of the repo. I haven't seen any kind of description of what modules are installed there and why, but I guess using the issues and/or pull requests is the way to go. In fact there's this closed issue which points in that direction, including a reference to ecosystem statistics, so I guess regarding your three questions.
There's no established procedure that I have been able to see.
Apparently, they look at statistics, after some developer asks for them.
I don't think that's the case. They at least have to pass all the tests in all platforms to be included. Also, I don't think my evolutionary algorithms module will be included any time soon.
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 7 years ago.
Improve this question
While using Gitflow, what is the reason for separating branch naming to feature vs bugfix vs hotfix?
I.e. why not just, for example, instead of:
feature/
bugfix/
hotfix/
Just do:
change/
What does separating by feature/bugfix/hotfix buy?
Great questions and the answer really depends on how you sort your git. The branching model and gitflow in general is trying to give us some order in the chaos that commits are just after a couple of days.
The image below shows you what they though makes most sense.
(As far as I know it all came from this blog post by Vincent Driessen)
Separating your hotfixes which merge directly into master and your bugfixes which merge into dev makes it easier to go with your product cycle.
The idea is you build your app, create features, make a release candidate (beta test) and then release your app. Hotfixs can be necessary at any time after this. No point in going back all the way to the feature branch and issuing a bug fix there as the feature may already been developed further.
Does that make sense?
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 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
Неllо. I develop system that works with stock exchange(system, below). And there is a lot of information my program need to interact with this system. This system has formal declared interface, but different details beside this declaration and requirements to my system is often changed. So how can I organize available information about this system and requirements to my program that it could be both easy to understand and easy to change.
Your first and foremost goal is to create documentation for the relevant APIs your program exposes and then add documentation for the configuration files, maybe even set up a validator for configuration that.
Automatically generated content from code annotations (depending on your solution, it might be .NET's XML docs or PHPdoc, etc.) is the first step – this will help you document classes and interfaces as you work on the code. The next step is documenting non-code assets. If you have XML configuration, you can write schemas to validate against, for example.
After that comes integration documentation – steps that need to be taken on the production server and/or workstations to install, upgrade and maintain the application, including support scripts.
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