I have a few sites that I maintain, each with varying amounts of custom code.
Until recently, I was the only developer, so I didn’t feel much of a need to document, but I now have two other developers that work on the projects.
So, I need to get more serious about maintaining codebases and documentation. What are some good software solutions to do this?
Github Codespaces seems like the most reasonable answer, but I’d really prefer an open source solution.
Well you should be writing good code comments on any code you do. Not only to remind future devs that may come onto the project, but for yourself too as you will forget things over time.
As for your situation, don’t you use a version control system like Git just to house your codebase? If you are commenting your code and version controlling those comments (along with any code documents you might also put into the project) then version control will keep a record for any new dev brought to the project.
There are hundreds and probably thousands of books about software design. Specifications are fundamental to Software Design. Using Software Design methodologies the entire system is documented.
Certainly it will be much work to retrofit an existing system to be designed as well as if it was developed using a Software Design methodology. The best solution however would be to document it as if it is a new system.
As for how, that is a matter of personal preference I think. Most developers prefer diagrams. UML is a popular way of diagramming systems. There are popular format for database designs, you probably can generate a graphical representation of the database using tools. My preference is to use text as much as possible to describe software but most developers do not prefer that.
I don’t currently use Git. I basically cowboy code everything, which is starting to expose some obvious problems…
One thing I am trying to decide is where to actually house the codebase. I’d rather not use Github proper. I’d much prefer to house the codebase on something like a VPS that I control.
I’ve looked into OpenVSCode, which is said to be an open source equivalent of Github Codespaces, but from installing it and playing around with it, it only looks to be VS Code running in the web browser. What is the “Github Codepsaces” about it?
I can understand your reluctance about using something like Github. But the fact that github skills are in demand (and it would be advantageous to learn them for jobs), companies all over the world trust Github, you can have your own private repositories and it universally works with most tools out there… you might want to reconsider. I can understand back when Github only had public repositories on their free plan, that has since changed.
If you still want to do things all privately, you can always set up your own git server using a tutorial like…
Maybe something to consider.
As for Github codespaces, I haven’t personally used it, but you can read all about it at the following link…
It is essentially a cloud service for a dev environment to work on projects. Where you can let someone else take care of the environment and you choose the requirements and tools to work with.
It has been a while since I have worked at a company that had standards and QA ant stuff like that for their applications. Do companies now consider Git to satisfy all documentation requirements?
You can self host your own GIT with JetBrains Space. There is a free Tier that should meet your needs.
I am not quite sure what you are asking here. I guess each company is different, but most companies do use git or github just for everyday development and often that includes projects like source code for their documentation sites as well. It really just depends on the company and their QA practices. Our company has several documentation sites that are backed up on repositories. Git is for version control and documentation needs versioning probably more than software these days as documentation is constantly updated.
Hopefully that answers the question.
The question here is, what are the Options for documenting code changes?
The suggestion is to use Git to document the system. I assume the suggestion was not to use Git to store the documentation but that a Git repository of the source code could be the documentation. If my understanding of that much is accurate then I am asking if the Git repository can be the only documentation.
In my opinion, a Git repository of a system cannot be the primary documentation and I will be surprised if any company’s standards say it is. Whether the documentation is in the repository is insignificant to here.
And why is that? You do know you can store more than just code in a git repository right? It is a version control system so you can certainly version control your documentation and you should. Does it have to be mixed in with your code project files? Not necessarily. I just suggested this could be one option. You can certainly create a git repository for your documentation, put all your docs in there, version them and such. Most companies do this because they will have a whole separate documentation web site that may outline their API’s use etc. Maybe a swagger project or something.
But to answer the original poster, one option is just to document with inline comments. Another option is to setup a git repository for stand-alone documentation documents. Mix them or keep them separate, it is all about your company’s needs.
OP, here are some examples… https://github.com/search?q=documentation
I am trying hard to say something else. Here you say documentation implying that there is something other than Git that is stored using Git. I am trying to refer to that something else. I do not know if UML can be versioned but let us assume it can be. Then UML is the documentation. Git is not the documentation, it is just a repository for storing it, just as a file system in a computer stores UML files. In my original reply I was not referring to Git as a way to store documentation. What I was commenting on originally is the implication that Git itself is documentation. I agree that the versions are useful but I was trying to say that there is a need for other documentation, the stuff you call documentation here.
This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.