[OT] Version Control and documentation

[James Cameron]

I'm using git for everything; private or public, single or
multiple systems, for source code and documentation.

I'm using Markdown for documentation, with tools to render as HTML and
PDF.

For documentation of APIs, I'm using doxygen or similar, with
documentation embedded in code comments.

The tools are operating system agnostic.

I was in a documentation writing tutorial session yesterday, and it
was interesting. I was to the right of the presenter at a desk by
myself with an orange laptop bag; which appears from about 26:33.

http://lca2018.linux.org.au/schedule/presentation/99/

When I say git above, I'm talking about git itself, not GitHub. I try
not to rely too much on the proprietary GitHub environment; that is,
if the data can be held in git, that's the best place for it, and
GitHub is only useful to me for short-term conversations with
collaborators.

So far I have not used any version control or documentation software.
Now I need one. I searched on the net. GIT seems to be good.
Before I commit to any, I would like opinion of experts on the list.
Please let me know what is being used and any suggestions.
Satyadev Vyas
--
http://www.piclist.com/techref/piclist PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist

[John J. McDonough]

So far I have not used any version control or documentation software.
Now I need one. I searched on the net. GIT seems to be good.
Before I commit to any, I would like opinion of experts on the list.
Please let me know what is being used and any suggestions.
Satyadev Vyas

Most of the version control systems out there are descendants of the old
RCS which itself was an answer to the even more ancient SCCS. The
popular ones mostly added some features to RCS to make collaboration a
little easier, with varying degrees of success. CVS, PVCS, Subversion
are all pretty much lipstick on RCS.

git was Linus' approach which is a huge departure from the earlier
systems. Instead of tracking individual files, git tracks the current
state of the project. Some technical wizardry also makes it much faster
than the others; with larger projects, MUCH faster. Tracking the project
rather than the files makes it much easier to go back in time.

There are features of git that I dislike, but once you get your head
around it, it is far easier to use than its predecessors. MPLAB-X
integrates fairly well with git as well. Personally, I'm an old command
line guy, so I do almost everything from the command line, but there are
a few git GUIs I use from time to time because they give a nice view of
the branches.

And branches are a big advantage on git. With the earlier systems,
branches were costly, slow and clumsy. With git, branches are cheap and
easy. Branches allow you to take off on a new version or feature set,
and still maintain the original. When the new features are ready, simply
merge the development branch back into the main branch. There are a
number of recommended schemes for doing this.

There are also a number of public repositories. These allow you a backup
copy of your project offsite cheaply and easily. I happen to like
gitlab, but there are a bunch of others. I simply type "git push" and in
a few seconds my project is backed up off site. Plus, I can allow
collaborators access to my project, with varying levels of authority.

Almost all new, large, open source projects use git. While it is a
departure from the older systems, it is so much faster that there is
really no other choice.

--McD

[Christopher Head]

Post by John J. McDonough
CVS, PVCS, Subversion
are all pretty much lipstick on RCS.


Instead of tracking individual files, git tracks the current state of the project.


Tracking the project rather than the files makes it much easier to go back in time.

While I agree with almost everything you said, Subversion’s revision number is a point in time snapshot of the project as a whole too, not of a single file. Not that this should detract from Git being better in lots of other ways.

[Harold Hallikainen]

Post by James Cameron
I'm using git for everything; private or public, single or
multiple systems, for source code and documentation.
I'm using Markdown for documentation, with tools to render as HTML and
PDF.
For documentation of APIs, I'm using doxygen or similar, with
documentation embedded in code comments.
The tools are operating system agnostic.
I was in a documentation writing tutorial session yesterday, and it
was interesting. I was to the right of the presenter at a desk by
myself with an orange laptop bag; which appears from about 26:33.
http://youtu.be/FJHsnqyvOjY
http://lca2018.linux.org.au/schedule/presentation/99/
When I say git above, I'm talking about git itself, not GitHub. I try
not to rely too much on the proprietary GitHub environment; that is,
if the data can be held in git, that's the best place for it, and
GitHub is only useful to me for short-term conversations with
collaborators.

So far I have not used any version control or documentation software.
Now I need one. I searched on the net. GIT seems to be good.
Before I commit to any, I would like opinion of experts on the list.
Please let me know what is being used and any suggestions.
Satyadev Vyas
--
http://www.piclist.com/techref/piclist PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist

--
James Cameron
http://quozl.netrek.org/

I've been using git for a couple months and, so far, so good. I found a
free git tutorial on Amazon helpful:
https://www.amazon.com/Rys-Git-Tutorial-Ryan-Hodson-ebook/dp/B00QFIA5OC/ref=sr_1_6?s=books&ie=UTF8&qid=1517070236&sr=1-6&keywords=git

I've heard of doxygen before but never used it. It does sound interesting.

Harold

[Matthew Miller]

I've used Mecurial for my personal projects at home for several years
now, but at work use git with an enterprise version of Github. Both
are very good version control systems. I do think that git is king of
the version control hill, having pushed aside the other contenders.

To highlight what James said about Markdown: some type of plain text
documentation is a must. It's helpful that Github understands
markdown, as well as org-mode which is my main way of documenting
things.

So far I have not used any version control or documentation software.
Now I need one. I searched on the net. GIT seems to be good.
Before I commit to any, I would like opinion of experts on the list.
Please let me know what is being used and any suggestions.
Satyadev Vyas
--
http://www.piclist.com/techref/piclist PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist