Tag Info

Hot answers tagged

59

Because it's extra effort to create and maintain such a document, and too many people don't understand the associated benefits. Many programmers aren't good technical writers (although many are); they rarely write documents strictly for human consumption, therefore they don't have practice and don't like doing it. Writing a code overview takes time that you ...


14

The dry, harsh truth? Documentation is not made because projects can do without it. Even open source projects often face stiff competition. Most of such projects don't start with large shoulders, they start off a bright idea, often a one man bright idea. As such, they can't afford the time and costs of hiring human documentors, even if they offered to ...


7

Overview documents such as you describe are rare even on commercial projects. They require extra effort with little value for the developers. Also developers tend not to write documentation unless they really need to. Some projects are lucky to have members who are good at technical writing, and as a result have good user documentation. Developer ...


6

As you can't control when the mobile apps will be updated to a new release, you need to version at least your REST API. If you don't it will be impossible to make backwards-incompatible changes to that interface. Besides the REST API, it is a good idea to version also the other communication interfaces that go over a network interface. That way, you are ...


5

I think you are taking on unwarranted personal risk here. It's clear from your question you already realize a larger development team is necessary, that you cannot continue to do the work of multiple people without making untenable compromises to the quality of your work, the quality of your life or both. As a software engineer, it will be up to you to ...


5

When used properly, VCS has too much detail. Every little change is recorded, when a changelog is generally for the big user-visible changes. In short, the target audience for a changelog is not the same as for the commit messages of the VCS. If you are disciplined, a changelog can be an auto-generated subset of what is in VCS, though in my experience most ...


5

Basically, you're completely right. All the information should be in the VCS as well, and as commenters said, changelogs are often generated out of VCS information. However, prepared changelogs come with some remarkable advantages: A changelog does not require to connect to the VCS, maybe install the proper VSC client before, scrolling through tons of ...


5

Are there things like these and I'm missing them? Things that do the same job as I am describing? There is an excellent book called The Architecture of Open Source Applications that provides detailed descriptions of a variety of high-profile open source software projects. However, I'm not sure if it exactly fills the role you're imagining, because I ...


4

Because there are far more open-source programmers than open-source technical writers. Documentation takes maintenance and time to keep up to date. The more bulky the documentation, the more it takes. And documentation that isn't in sync with the code is worse than useless: it misleads and conceals instead of revealing. A well documented code base is ...


3

This post makes an interesting point about your question. In a more practical way, if you have 3 components: 2 Consumers: a Front-End and a Mobile App 1 API provider: a Back-End You could use the typical M.m.p (Major.minor.patch) versioning scheme for each but, on your Back-End url you could put something as http://youhost/M.m/resourceURI. As you ...


3

To my understanding, LEAN development intends to optimize the development process of your team, with the focus on balancing between quality, costs and time. It is an organizational method, which does not embrace a specific syntax, language or notation. BDD, however, has its focus on "building the right software", and getting the requirements right, by using ...


2

What's the purpose of keeping a changelog if everyone uses their VCS properly? ... If this history is being properly kept, what is the purpose of manually keeping the same history in a regular file? Your question is a good one, but you're making two big assumptions. Given a team with a disciplined check-in history, you're assuming that the ...


2

I created a module that generate class diagram for javascript/node/html/css. Its based on the "WAE" extension of UML. Its called wavi. For javascript, function,variable and use of other modules are automatically recognized. You can use it for documenting your application. https://www.npmjs.org/package/wavi


1

I recommend you install a continuous integration server, hook it up to your code repository and a snapshot/release repository and automate your builds. This will have a number of advantages: Every component will be versioned when it is released. This includes low-level libraries as well as your final products. Every code commit will trigger a snapshot ...


1

First, I'm lets start off by framing the problem a little differently. You've asked which pieces of software you need to "version". Version is an overloaded term in CS, and could mean about 100 different things. The primary things I would look at is: Version Control - Version control is a configuration management tool that helps you keep track of snapshots ...



Only top voted, non community-wiki answers of a minimum length are eligible