A place for documentation #16
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
There should be a place for for documentation for things that are non code related, like new_projects.md. Weather that's this repo (
meta-tasks) or a dedicated repo, TWS/Docs, TWS/Getting-Started, TWS/The-Big-Book-Of-Everything?Documentation can be related to anything "TWS" related but not project specific related. I'm thinking things like, getting started, how to create a new project, the bylaws, how to submit a pull request, recommended software/tool chains. Anything a new comer could be referenced to to get caught up.
I can see documentation go two ways:
A
docfolder in the main repo.This would contain markdown files in a hierarchy which would be easy git-able and browsable via the Forgejo code viewer. It would also allow for easy deployment for a static site generator to build a dedicated website, say docs.tams.tech. One could still utilize the PR method and documentation would need to be reviewed before merge.
Use the Wiki built into Forgejo.
This can keep the main "meta" repository clean. The Wiki doesn't require PR request so anyone with access can make changes, the true spirit of the Wiki.
Fun fact the Wiki is itself actually a git repo you can clone,
git clone https://git.tams.tech/TWS/meta-tasks.wiki.git. So one could still clone and build a dedicated static site from it's contents.Another option is a dedicated wiki software such as MediaWiki.
This is true and I was thinking the exact same thing after I submitted it. This has the benefit of being off in its own world, dedicated to documentation.
Currently though Forgejo seems to be the only infrastructure being utilized at the moment (correct me if I am wrong) and until a dedicated doc site comes available, personalty I think here is a good place to start.
I also had the thought of if there was any thoughts on utilizing a dedicated ticket tracker for customers, like OSTicket. Ticket trackers too seem to have dedicated knowlagebase/wikis built in. I am not entirely for this one though as this seems this would be more suited for "how to solve a particular issue / how to handle customers" kind of documentation.
I can spin up a MediaWiki real quick if it would be helpful. Not to say that I'm against other options. I don't have any experience with ticket tracking sw like that, at least on the hosting side
I guess the benefits to a documentation repo is portability (it's just git) and simple to set up with current infrastructure, even if it lacks some bells and whistles.
While I really like MediaWiki, I think it would be more accessible to standardize on Markdown than to require everyone to learn two separate markup languages for documentation and project management. Because of that and the reasons @todtb mentioned, I propose the following:
TWS/meta.Though maybe this is confusing compared to just using the files or the Wiki, and we should just use one of them? But, for example, if we wanted to have a PDF copy of something, could the wiki handle that? Or is it just markdown?
The wiki seems to just be markdown. So, either we use the wiki for documentation and the repo for documents, or we just use the repo for documentation and documents and ignore the wiki. I lean towards the former, I think the wiki interface will be something we want to use for that area.
That's a bummer. I see there is an open request for it. Gitlab has the feature and I just assumed Gitea/Forgejo had the functionality too because it seemed so basic.
Don't you have a Nextcloud? You could use a folder to contain resources for the wiki? I have done that with Seafile for files I don't want to git. Downside is if the domain changed all the resource links need to be updated.
That's a good point, that's what we have right now. I had been thinking at the time of converting the bylaws to markdown and creating a pull request so that we can all review it and make changes, with review approval marking consensus. Nextcloud doesn't have any such functionality (of course), but it is the appropriate place to store generic PDF documents and stuff like that.
I do need to finish up the Nextcloud, and I may rope you into that if I get stuck, Evan 😂