Documentation update for next release #64

Closed
opened 2019-10-28 10:49:25 +00:00 by asdf · 17 comments
Collaborator

For the next release (2.0.0) we should complete a review of the documentation. This task might involve:

(list amended)

  • README.md
  • The branch 'update-readme' has some updates that will need to be added.
  • Add a picture
  • Final review - sloum
  • man page bombadillo.1
  • Document completed - sloum
  • Final review - asdf
  • http://bombadillo.colorfield.space
  • Draft release notes - asdf & sloum
  • Review User guide - asdf
  • Review Main page - asdf
  • Review, upload changes - sloum
  • Add binaries and link them on binaries page - sloum
  • gopher://bombadillo.colorfield.space
  • Update content to match website - asdf & sloum
  • Add binaries and link them on binaries page - sloum
  • http://rawtext.club/~sloum/bombadillo
  • Add link redirecting to bombadillo.colorfield.space - sloum

It's likely that this task cannot be completed until all features for 2.0.0 are confirmed.

For the next release (2.0.0) we should complete a review of the documentation. This task might involve: (list amended) - [x] README.md - [x] The branch 'update-readme' has some updates that will need to be added. - [x] Add a picture - [x] Final review - sloum - [x] man page bombadillo.1 - [x] Document completed - sloum - [x] Final review - asdf - [x] http://bombadillo.colorfield.space - [x] Draft release notes - asdf & sloum - [x] Review User guide - asdf - [x] Review Main page - asdf - [x] Review, upload changes - sloum - [x] Add binaries and link them on binaries page - sloum - [x] gopher://bombadillo.colorfield.space - [x] Update content to match website - asdf & sloum - [x] Add binaries and link them on binaries page - sloum - [x] http://rawtext.club/~sloum/bombadillo - [x] Add link redirecting to bombadillo.colorfield.space - sloum It's likely that this task cannot be completed until all features for 2.0.0 are confirmed.
asdf self-assigned this 2019-10-28 10:49:26 +00:00
sloum was assigned by asdf 2019-10-28 10:49:26 +00:00
asdf added the
documentation
label 2019-10-28 10:49:26 +00:00
Owner

This is great. I definitely think getting all of this in order is a good call.

For the last question (are there opportunities for consolidation). I have mostly tried to let each piece of documentation serve a specific purpose. My thoughts currently are as follows:

Document Purpose Status
README.md Build/install instructions, basic description of application Review before release. Will need minor edits.
LICENSE Provide information about GPLv3 This should not need changes.
bobmadillo.colorfield.space (web) Web home/user focused. Quickstart guide, dev log, fingerpost (where to go for other info), may eventually provide prebuilt binaries. Review main page & quickstart. The dev log is probably fine.
bobmadillo.colorfield.space (gopher) Mostly a mirror of the web site. Review to make sure there are no malformed links. Any changes made to web version will likely need to be made for gopher.
bombadillo.colorfield.space (gemini) Mirror the web/gopher versions This has not been created yet. Hold off until after release.
rawtext.club/~sloum/bombadillo Old documentation site. Solid docs for 1.x series. May need to be retired for 2.0.0 in favor of the colorfield.space version. Maybe provide a forward link?
man page (bombadillo.1) Main source of technical documentation. Pretty solid. Will need review and, likely, minor edits before release.
This is great. I definitely think getting all of this in order is a good call. For the last question (are there opportunities for consolidation). I have mostly tried to let each piece of documentation serve a specific purpose. My thoughts currently are as follows: | Document | Purpose | Status | |--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| | README.md | Build/install instructions, basic description of application | Review before release. Will need minor edits. | | LICENSE | Provide information about GPLv3 | This should not need changes. | | bobmadillo.colorfield.space (web) | Web home/user focused. Quickstart guide, dev log, fingerpost (where to go for other info), may eventually provide prebuilt binaries. | Review main page & quickstart. The dev log is probably fine. | | bobmadillo.colorfield.space (gopher) | Mostly a mirror of the web site. | Review to make sure there are no malformed links. Any changes made to web version will likely need to be made for gopher. | | bombadillo.colorfield.space (gemini) | Mirror the web/gopher versions | This has not been created yet. Hold off until after release. | | rawtext.club/~sloum/bombadillo | Old documentation site. | Solid docs for 1.x series. May need to be retired for 2.0.0 in favor of the colorfield.space version. Maybe provide a forward link? | | man page (bombadillo.1) | Main source of technical documentation. | Pretty solid. Will need review and, likely, minor edits before release. |
Owner

I have made some changes to the branch update-readme to bring it more inline with our current state of things. If you get a chance I would love a second set of eyes on it. Feel free to re-word/re-work as you see fit.

I have made some changes to the branch `update-readme` to bring it more inline with our current state of things. If you get a chance I would love a second set of eyes on it. Feel free to re-word/re-work as you see fit.
Author
Collaborator

Thanks for the feedback on this, it matches pretty well with what I was thinking too.

I've made a commit to update-readme but will need some more time on it. I'll continue work on it when I'm next free.

Thanks for the feedback on this, it matches pretty well with what I was thinking too. I've made a commit to update-readme but will need some more time on it. I'll continue work on it when I'm next free.
Owner

Cool. The changes you made to update-readme look good. :)

Cool. The changes you made to `update-readme` look good. :)
Author
Collaborator

I've reviewed bombadillo.colorfield.space, both web and gopher.

Words like 'opperating' are misspelt on both. the web page also has 'certicicate', the gopher page 'BOMBDADILLO'.

There are a few references to the upcoming changes - version 2 is coming, expect consolidation as we near version 2 - these should change, but I'd recommend removing them anyway, to avoid having to maintain them.

I'm not sure if you would like some more help with this - I can download and modify the pages directly maybe?

I've reviewed bombadillo.colorfield.space, both web and gopher. Words like 'opperating' are misspelt on both. the web page also has 'certicicate', the gopher page 'BOMBDADILLO'. There are a few references to the upcoming changes - version 2 is coming, expect consolidation as we near version 2 - these should change, but I'd recommend removing them anyway, to avoid having to maintain them. I'm not sure if you would like some more help with this - I can download and modify the pages directly maybe?
Owner

You should have repo access if you want to update directly and then I can pull it to the server after it gets merged in. That said, I am definitely able to take care of those and appreciate you finding them. My typing is not always the best, lol. Let me know your preference.

You should have repo access if you _want_ to update directly and then I can pull it to the server after it gets merged in. That said, I am definitely able to take care of those and appreciate you finding them. My typing is not always the best, lol. Let me know your preference.
Owner

Ok. I went through and updated the spelling mistakes that you mentioned (the ones I was able to find anyway). I did not find much of the 2.0 references with the web version (though it is possible I missed them), but did find a bunch on gopher and removed them in most places. I also made sure that non-web browser was in use.

Ok. I went through and updated the spelling mistakes that you mentioned (the ones I was able to find anyway). I did not find much of the 2.0 references with the web version (though it is possible I missed them), but did find a bunch on gopher and removed them in most places. I also made sure that non-web browser was in use.
Author
Collaborator

Thanks for that. I had posted that before I had access to the repo, but did not get to it yet as I have to configure my editor to match the style.

Also, don't forget, you can :set spell in vim :)

Thanks for that. I had posted that before I had access to the repo, but did not get to it yet as I have to configure my editor to match the style. Also, don't forget, you can `:set spell` in vim :)
Owner

Hahaha. True. I never think of it. I should do so, in particular for content heavy things.

Hahaha. True. I never think of it. I should do so, in particular for content heavy things.
Owner

I have added a box at the top of https://rawtext.club/~sloum/bombadillo.html with the following text: This page contains legacy documentation for Bombadillo 1.0. Please visit bombadillo.colorfield.space for documentation of more recent/current versions of Bombadillo.

That should be satisfactory to make sure people understand that they are looking at old info and get them routed to a new location if that is what they want.

I have added a box at the top of https://rawtext.club/~sloum/bombadillo.html with the following text: `This page contains legacy documentation for Bombadillo 1.0. Please visit bombadillo.colorfield.space for documentation of more recent/current versions of Bombadillo.` That should be satisfactory to make sure people understand that they are looking at old info and get them routed to a new location if that is what they want.
Author
Collaborator

Cool. Also, that box looks really nice.

Cool. Also, that box looks really nice.
Owner

Thanks!

At what point do you think the website updates should be pushed? We could push now, but there wont be an actual release to tie things to yet... Not sure how the timing should work out to synchronize all of this. I doubt there is a lot of traffic going to the site currently....

Thanks! At what point do you think the website updates should be pushed? We could push now, but there wont be an actual release to tie things to yet... Not sure how the timing should work out to synchronize all of this. I doubt there is a lot of traffic going to the site currently....
Author
Collaborator

It can be put up at any time really, but to be complete it needs 2.0.0 binaries and the 2.0.0 tag.

It can be put up at any time really, but to be complete it needs 2.0.0 binaries and the 2.0.0 tag.
Owner

I just went through the checklist above. If we agree we are at code freeze (which I think we are now), then I can generate binaries and get them added to gopher and to the website.

The code freeze also means that final run-throughs of the man page and README can be done. I'll wait for your comment in response here, but then I'll go through the README to do a final check.

I just went through the checklist above. If we agree we are at code freeze (which I _think_ we are now), then I can generate binaries and get them added to gopher and to the website. The code freeze also means that final run-throughs of the man page and README can be done. I'll wait for your comment in response here, but then I'll go through the README to do a final check.
Author
Collaborator

Yeah I think we should be at code freeze now. Exciting!

Yeah I think we should be at code freeze now. Exciting!
Owner

I have conducted a final reaview of the README. Everything looks good except one incorrect word. I have opened a PR correcting it here: #104 .

That leaves the man page review and binary generation. I believe you had intended to do the man page review.

Once the review is complete I think we should merge into master with a tag 2.0.0 and set it as a release. Then I will generate binaries and get them set up on the gopher and web pages.

At that point we move to announcing the release via notes in issue #72

I have conducted a final reaview of the README. Everything looks good except one incorrect word. I have opened a PR correcting it here: #104 . That leaves the man page review and binary generation. I believe you had intended to do the man page review. Once the review is complete I think we should merge into master with a tag 2.0.0 and set it as a release. Then I will generate binaries and get them set up on the gopher and web pages. At that point we move to announcing the release via notes in issue #72
Owner

The executables have been added to gopher and the web. They are zip files containing:

  • bombadillo
  • bombadillo.1
  • LICENSE
  • INFO (a file with brief description of the other files and links to more information)

That was the last thing unchecked for this issue. I am closing. Definitely let me know if anything else is spotted that should be done.

The executables have been added to gopher and the web. They are zip files containing: - bombadillo - bombadillo.1 - LICENSE - INFO (a file with brief description of the other files and links to more information) That was the last thing unchecked for this issue. I am closing. Definitely let me know if anything else is spotted that should be done.
sloum closed this issue 2019-12-02 05:39:41 +00:00
Sign in to join this conversation.
No Milestone
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: sloum/bombadillo#64
No description provided.