Editorial updates of documentation by matsduf · Pull Request #1171 · zonemaster/zonemaster

matsduf · 2023-06-22T15:33:47Z

Purpose

Makes it easier to navigate to the SUMMARY structure.
Makes a list of user guides.
Adds missing test zones to the structure and README
Updates Wishlist (relates to Update Wishlist #629)

Changes

README.md
docs/public/SUMMARY.md

and several other files.

How to test this PR

Review.

tgreenx

I suggest to include this PR in 2023.1.1.

tgreenx

I did another pass through all README.md and other main documents in docs/public/ and found the following nits below. Moreover I think the file WISHLIST.md can be updated: items 2, 3, 4, 8 (soonTM) can all be removed, possibly items 5 and 6 too.

Additional changes suggestions:

The the -> Then the

zonemaster/docs/public/using/README.md

Line 17 in c7c6793

has to install the [Zonemaster-Backend] and the [Zonemaster-GUI]. The the

This if -> This is

zonemaster/docs/contact-and-mailing-lists.md

Line 19 in c7c6793

list. This if for one-way communication only.

do -> does

zonemaster/docs/contact-and-mailing-lists.md

Line 49 in c7c6793

If Zonemaster do not report when there is a DNS error, or if

not with -> not work with

zonemaster/test-zone-data/README.md

Line 24 in c7c6793

latest version of Zonemaster (it will not with older version than v2022.2,

Adress-TP -> Address-TP

zonemaster/test-zone-data/README.md

Line 136 in c7c6793

    
           * Directory structure for scenarios for test cases in the Adress-TP test module.

…ew comments

matsduf · 2023-06-28T16:39:39Z

@PNAX and @tgreenx, please re-review.

ghost · 2023-06-29T09:48:27Z

+        - [DNSSEC-TP](specifications/test-zones/DNSSEC-TP)
+        - [Nameserver-TP](specifications/test-zones/Nameserver-TP)
+        - [Zone-TP](specifications/test-zones/Zone-TP)


Such entries will prevent building the documentation. They should link to a document not a folder.

Will fix by including READMEs.

ghost · 2023-06-29T09:51:35Z

+*Click on [SUMMARY](../SUMMARY.md) to view a linked tree structur of all documents
+under "public".*


This will create a broken link when building the HTML documentation. The SUMMARY.md file won't have any HTML counterpart. I suggest removing this paragraph (and all similar paragraphs in the other documents).

Is the name SUMMARY.md magic? If I create a symlink TREE.md --> SUMMARY.md will then TREE.md get an HTML counterpart?

I really want to use the SUMMARY.md since it is very helpful for the users instead walking through the README.md files.

No there is no magic, as the documentation says: "The summary file is used by mdBook to know what chapters to include, in what order they should appear, what their hierarchy is and where the source files are. Without this file, there is no book."
In order to have an HTML file, you need to list the Markdown file into SUMMARY.md. And currently, I don't feel at ease with listing SUMMARY.md into itself.

I understand what you mean, but the SUMMARY file is really useful when navigating in the document tree. I think it would be wrong to hide it for the readers in Github.

The new docs/public/README.md is not included in SUMMARY.md and I guess that it does not have to be included, and then I can keep the link in that README, but remove it from the other READMEs.

Now that I better understand how it works I can see that there were some documents under specification/test-zones that were missing.

Well it could be an idea to include the docs/public/README.md to the SUMMARY.md file. In this way, the landing page would be this README file.

diff --git a/docs/public/SUMMARY.md b/docs/public/SUMMARY.md index 33738dda..86fa3090 100644 --- a/docs/public/SUMMARY.md +++ b/docs/public/SUMMARY.md @@ -2,6 +2,7 @@ https://rust-lang.github.io/mdBook/format/summary.html --> # Documents in public document tree +- [Introduction](README.md) - [Installation](installation/README.md) - [Prerequisites](installation/prerequisites.md) - [Zonemaster-LDNS](installation/zonemaster-ldns.md)

If docs/public/README.md is included in SUMMARY.md then it cannot link to SUMMARY.md. I prefer to have it this way. I really want to be able to link to SUMMARY.md for Github users.

tgreenx · 2023-06-29T09:55:14Z

I changed the milestone to v2023.1.1, as discussed in our latest meeting.

matsduf · 2023-06-29T14:27:19Z

@PNAX and @tgreenx, please re-review.

matsduf · 2023-06-29T15:33:24Z

I changed the milestone to v2023.1.1, as discussed in our latest meeting.

That is fine. I was waiting for the final approval. I changed the base branch to release-branch-v2023.1.1.

marc-vanderwal · 2023-07-04T13:48:03Z

+3.  Developing a Mobile app
+4.  Parallel tests
+5.  It would be nice to test if unknown RR types can be queried (Ref :
+    https://savannah.nongnu.org/bugs/?36909)


Item number 5 in this wish list is something that could be implemented in a reasonable amount of time. Do we have an issue on the zonemaster-engine repo for this?

I do not know.

I can see that there was one, which was (surprisingly) opened for only a few days: #323

marc-vanderwal · 2023-07-04T14:18:03Z

+
+## Elaboration of the Test Case
+
+Test cases are written for almost all Test Requirement. There could be the case


Suggested change

Test cases are written for almost all Test Requirement. There could be the case

Test cases are written for almost all Test Requirements. There could be the case

matsduf · 2023-07-04T14:57:10Z

@PNAX, @tgreenx and @marc-vanderwal, please re-review.

tgreenx · 2023-07-05T08:26:52Z

+3.  Developing a Mobile app
+4.  Parallel tests
+5.  It would be nice to test if unknown RR types can be queried (Ref :
+    https://savannah.nongnu.org/bugs/?36909)


I can see that there was one, which was (surprisingly) opened for only a few days: #323

marc-vanderwal

Looks good to me.

Editorial updates

7b84daa

matsduf added A-Documentation Area: Documentation only. V-Patch Versioning: The change gives an update of patch in version. labels Jun 22, 2023

matsduf added this to the v2023.2 milestone Jun 22, 2023

matsduf requested review from a user, hannaeko, marc-vanderwal, mattias-p and tgreenx June 22, 2023 15:33

ghost reviewed Jun 22, 2023

View reviewed changes

Comment thread README.md Outdated

Comment thread docs/public/specifications/README.md Outdated

Editorial updates

20e8d7d

matsduf requested a review from a user June 23, 2023 18:58

tgreenx reviewed Jun 28, 2023

View reviewed changes

Comment thread README.md Outdated

Comment thread docs/public/specifications/README.md Outdated

Comment thread docs/public/specifications/README.md Outdated

tgreenx reviewed Jun 28, 2023

View reviewed changes

Adds additional editorial changes, improvements and changes from revi…

3b38234

…ew comments

matsduf requested a review from tgreenx June 28, 2023 16:27

matsduf added 3 commits June 28, 2023 18:31

Cleaned-up

e68cd95

Updates from review comments

9c9baa9

Editorial updates

b95a751

ghost reviewed Jun 29, 2023

View reviewed changes

tgreenx reviewed Jun 29, 2023

View reviewed changes

tgreenx modified the milestones: v2023.2, v2023.1.1 Jun 29, 2023

Editorial updates and updates based on review comments

6dcc1ed

matsduf requested review from a user and tgreenx June 29, 2023 14:26

matsduf changed the base branch from develop to release-branch-v2023.1.1 June 29, 2023 15:32

marc-vanderwal reviewed Jul 4, 2023

View reviewed changes

Update based on review comments

05f6d6f

matsduf requested a review from marc-vanderwal July 4, 2023 14:56

tgreenx approved these changes Jul 5, 2023

View reviewed changes

marc-vanderwal approved these changes Jul 12, 2023

View reviewed changes

matsduf merged commit 56b51aa into zonemaster:releases/v2023.1.1 Jul 12, 2023

matsduf deleted the update-general-documentation branch July 25, 2023 13:11

tgreenx linked an issue Aug 9, 2023 that may be closed by this pull request

Update Wishlist #629

Closed

tgreenx mentioned this pull request Aug 9, 2023

Update Wishlist #629

Closed

tgreenx linked an issue Aug 9, 2023 that may be closed by this pull request

Update Zonemaster users guide #630

Closed

tgreenx mentioned this pull request Aug 9, 2023

Update Zonemaster users guide #630

Closed

		*Click on [SUMMARY](../SUMMARY.md) to view a linked tree structur of all documents
		under "public".*


		## Elaboration of the Test Case

		Test cases are written for almost all Test Requirement. There could be the case

Uh oh!

Conversation

matsduf commented Jun 22, 2023 • edited by tgreenx Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

Changes

How to test this PR

Uh oh!

Uh oh!

Uh oh!

tgreenx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgreenx left a comment

Choose a reason for hiding this comment

Additional changes suggestions:

Uh oh!

matsduf commented Jun 28, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tgreenx commented Jun 29, 2023

Uh oh!

matsduf commented Jun 29, 2023

Uh oh!

matsduf commented Jun 29, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matsduf commented Jul 4, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marc-vanderwal left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

matsduf commented Jun 22, 2023 •

edited by tgreenx

Loading