Skip to content
This repository has been archived by the owner on Oct 15, 2024. It is now read-only.

restructure documentation #4501

Closed
17 tasks
markus2330 opened this issue Sep 30, 2022 · 6 comments
Closed
17 tasks

restructure documentation #4501

markus2330 opened this issue Sep 30, 2022 · 6 comments
Labels
floss2022w stale triage needed Issue needs clarifications.

Comments

@markus2330
Copy link
Contributor

markus2330 commented Sep 30, 2022 •
edited
Loading

As discussed in #4436, we would like split docu in 3 parts:

  • user docu: in doc/help
  • dev docu: in doc/dev
  • contributor docu: in doc/contrib

So following changes in the documentation are needed (TBD: not yet complete)

  • scripts/sed -> scripts/dev/spellings.sed
  • doc/BUILDSERVER.md -> doc/contrib/buildserver.md
  • doc/BIGPICTURE.md -> doc/dev/intro/bigpicture.md
  • doc/CODING.md -> doc/contrib/coding.md
  • doc/DESIGN.md -> doc/dev/design/README.md (review parts to doc/contrib/review.md)
  • doc/DEBUGGING.md -> doc/contrib/debugging.md
  • doc/GETSTARTED.md -> doc/contrib/getstarted.md
  • doc/GIT.md -> doc/contrib/git.md
  • doc/KEYNAMES.md -> doc/dev/design/keynames.md
  • doc/SECURITY.md -> doc/dev/design/security.md
  • doc/VISION.md -> doc/dev/intro/vision.md
  • doc/WHO.md -> doc/dev/intro/who.md
  • doc/WHY.md -> doc/dev/intro/why.md
  • doc/VERSION.md -> doc/dev/design/version.md
  • doc/help/elektra-contracts.md -> doc/dev/plugins/contract.md
  • doc/help -> doc/help
  • doc/man -> doc/help/man (within subfolders)
@markus2330 markus2330 self-assigned this Sep 30, 2022
@kodebach
Copy link
Member

doc/help -> doc/help/man
doc/man -> doc/help/man (within subfolders)

I would do doc/man/* -> doc/help/man/* and doc/help -> doc/help/markdown/*. I would also use folders for the markdown files with the same numbered sections, to make it more clear what manpage and markdown files belong together. We should also use these sections on the website, or maybe even more structure. Currently it's just one page with a giant list on the side.

scripts/sed -> doc/spellings.sed

I would just rename it to scripts/dev/spelling.sed. Not sure why you want to put it into doc. If you want to document the correct spellings for contributors, I'd create doc/contrib/spelling.md with contents along the lines of

# Spelling

We use American English spelling.
To fix common mistakes and some Elektra specific terms you can use `scripts/dev/fix-spelling`.
Also take a look at `scripts/dev/spelling.sed` which lists the replacements used by the script.

Here there shouldn't be any duplication.

In general I'd say there shouldn't be any duplication within doc/dev or doc/contrib. In doc/help it is more acceptable, but should be kept to a minimum. Duplicate information across the three folders is totally fine, as long as things are described on different levels.

@markus2330
Copy link
Contributor Author

doc/help/markdown/*

As nearly everything is markdown, this is confusing.

We should also use these sections on the website, or maybe even more structure. Currently it's just one page with a giant list on the side.

Any proposal how to structure them?

I would just rename it to scripts/dev/spelling.sed.

Ok, I updated above.

doc/contrib/spelling.md

This is already covered in doc/contrib/documentation.md

shouldn't be any duplication within doc/dev or doc/contrib. In doc/help it is more acceptable, but should be kept to a minimum. Duplicate information across the three folders is totally fine, as long as things are described on different levels.

👍

@kodebach
Copy link
Member

kodebach commented Oct 8, 2022

As nearly everything is markdown, this is confusing.

The at least do doc/help for markdown sources and doc/help/man for the generated roff.

Any proposal how to structure them?

Nothing concrete, but I find the current website so bad that I normally either look in my local repo copy or on GitHub. Like I already said, I think we need a dedicated person to update the website and I think web development could be popular for a thesis.

@markus2330 markus2330 mentioned this issue Oct 15, 2022
Closed
@markus2330 markus2330 added triage needed Issue needs clarifications. floss2022w labels Oct 15, 2022
@markus2330
Copy link
Contributor Author

I created more renamings.

I think a tool should be written first which does search&replace for all links.

@flo91 flo91 changed the title restructure documentation [FLOSS] restructure documentation Oct 18, 2022
@flo91 flo91 changed the title [FLOSS] restructure documentation restructure documentation Oct 18, 2022
@markus2330 markus2330 mentioned this issue Nov 3, 2022
Merged
23 tasks
@markus2330 markus2330 removed their assignment Nov 17, 2022
This was referenced Nov 24, 2022
Merged
Merged
@github-actions GitHub Actions
Copy link

I mark this stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping by writing a message here or create a new issue with the remainder of this issue.
Thank you for your contributions 💖

@github-actions github-actions bot added the stale label Nov 18, 2023
@github-actions GitHub Actions
Copy link

github-actions bot commented Dec 3, 2023

I closed this now because it has been inactive for more than one year. If I closed it by mistake, please do not hesitate to reopen it or create a new issue with the remainder of this issue.
Thank you for your contributions 💖

@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Dec 3, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
floss2022w stale triage needed Issue needs clarifications.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@markus2330 @kodebach