Refactoring Documentation for Explanations and Consistent Structure #5

ianmilligan1 · 2019-10-21T14:13:07Z

This branch/PR will see me:

fleshing out an Index.md with a site-wide table of contents;
providing some basic introduction;
some context on RDD/DF; and
breaking the large "getting started and overview" document into at least two parts.

I'll ping when ready for review.


        Beginning work on index document, will open PR


        minor fix to table of contents


        Adding bold to table of content headings

lintool · 2019-10-21T14:36:30Z

Progress in terms of rendered content here: https://github.com/archivesunleashed/aut-docs-new/tree/refactor-docs

@ianmilligan1 I previously misspoke, index should be README.md for GitHub to render automatically on front page


        Table of contents to text analysis section


        Renaming Index.md -> README.md


        Toc/DF placeholders for link analysis


        ToC/DF Placeholders for Image Analysis


        Major commit; update READMe, add filters, install

lintool · 2019-10-21T17:07:30Z

current/link-analysis.md

@@ -11,7 +19,9 @@ Most of the following examples show the **domain** to **domain** links. For exam

 We do provide one example below that provides raw data, however.

-### Extraction of Simple Site Link Structure
+## Extraction of Simple Site Link Structure


Let's rephrase everything so the headings can be of the form "How do I..."
So, something like "Extract Simple Site Link Structure"?

lintool · 2019-10-21T17:08:06Z

current/text-analysis.md

@@ -1,7 +1,21 @@
+# Plain Text Extraction


Highest-level heading should be "Text Analysis"?


        Adding new filter page to README

ianmilligan1 · 2019-10-21T17:13:18Z

Thanks @lintool - I'm going to take this out of review and begin implementing your suggested changes.

@lintool


        @lintool review

ianmilligan1 · 2019-10-21T17:19:21Z

I think I'll leave the text analysis as is - it's more straightforward (links was the most awkward as you flagged).

lintool · 2019-10-21T17:20:02Z

Another suggestion, see what you think:

At top level, we should just have

current/
r0.17.0/
r0.18.0/
README.md

The top README.md just says - here are the three versions.
Everything else should be moved into current/. So the "real" table of contents should be current/README.md.

That way, when we release r0.19.0, we'd just

cp -r current/ r0.19.0/

Update the main README.md, and start over.

ianmilligan1 · 2019-10-21T17:21:52Z

@lintool that makes sense to me, and is a lot cleaner!


        Adds missing DF import; resolves #4


        Create README.md


        Update README.md


        Update README.md


        Update README.md


        Lots of renaming.


        Update README.md


        Update README.md

lintool · 2019-10-21T17:48:28Z

@ianmilligan1 changed structure as I suggested.

ruebot

Just one question

ruebot · 2019-10-21T18:08:44Z

README.md

+
+Documentation from previous releases are also available:
+
+ [r0.18.0](r0.18.0/README.md)


The git tags are aut-0.18.0, etc. Let's use that, unless we're using the r for alphanumeric sorting.

[nruest@wombat:aut] (git)-[master]-$ git tag aut-0.10.0 aut-0.11.0 aut-0.12.0 aut-0.12.1 aut-0.12.2 aut-0.13.0 aut-0.14.0 aut-0.15.0 aut-0.16.0 aut-0.17.0 aut-0.17.1 aut-0.18.0 aut-0.9.0

(I'll push it to the branch and take care of it once we have consensus.)

yup, using the tags makes sense to me. Let's do that.
@ruebot do it, and then I'll merge this doc drop.


        r0.x.0 -> aut-0.x.0

ianmilligan1 added 3 commits Oct 21, 2019

Beginning work on index document, will open PR

ef6448b

minor fix to table of contents

667892c

Adding bold to table of content headings

23daf4e

ianmilligan1 added 5 commits Oct 21, 2019

Table of contents to text analysis section

fb13f22

Renaming Index.md -> README.md

77b206f

Toc/DF placeholders for link analysis

88f293e

ToC/DF Placeholders for Image Analysis

1a8f35a

Major commit; update READMe, add filters, install

6e9065a

lintool reviewed Oct 21, 2019

View changes

current/text-analysis.md Outdated

@@ -1,7 +1,21 @@

# Plain Text Extraction

This comment has been minimized.

Sign in to view

Copy link

lintool Oct 21, 2019
Member

Highest-level heading should be "Text Analysis"?

Adding new filter page to README

7077aad

ianmilligan1 marked this pull request as ready for review Oct 21, 2019

@lintool review

6377a4c

ianmilligan1 and others added 8 commits Oct 21, 2019

Adds missing DF import; resolves #4

90414de

Create README.md

Verified

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits

3011cbb

Update README.md

Verified

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits

47405cb

Update README.md

Verified

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits

232ae67

Update README.md

Verified

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits

0b7b712

Lots of renaming.

25407b4

Update README.md

Verified

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits

e1b4fe4

Update README.md

Verified

This commit was created on GitHub.com and signed with a verified signature using GitHub’s key.

GPG key ID: 4AEE18F83AFDEB23 Learn about signing commits

0905dfa

ruebot approved these changes Oct 21, 2019

View changes

r0.x.0 -> aut-0.x.0

Verified

This commit was signed with a verified signature.

ruebot Nick Ruest

GPG key ID: 417FAF1A0E1080CD Learn about signing commits

868738d

ruebot merged commit 95a7559 into master Oct 21, 2019

lintool deleted the refactor-docs branch Oct 21, 2019

archivesunleashed / aut-docs

Refactoring Documentation for Explanations and Consistent Structure #5

Refactoring Documentation for Explanations and Consistent Structure #5

ianmilligan1 commented Oct 21, 2019

This comment has been minimized.

lintool commented Oct 21, 2019

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

ianmilligan1 commented Oct 21, 2019 •

edited

This comment has been minimized.

ianmilligan1 commented Oct 21, 2019

This comment has been minimized.

lintool commented Oct 21, 2019

This comment has been minimized.

ianmilligan1 commented Oct 21, 2019

This comment has been minimized.

lintool commented Oct 21, 2019

ruebot left a comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.


		Documentation from previous releases are also available:

		+ [r0.18.0](r0.18.0/README.md)

archivesunleashed / aut-docs

Join GitHub today

Refactoring Documentation for Explanations and Consistent Structure #5

Refactoring Documentation for Explanations and Consistent Structure #5

Conversation

ianmilligan1 commented Oct 21, 2019

This comment has been minimized.

lintool commented Oct 21, 2019

This comment has been minimized.

lintool Oct 21, 2019

This comment has been minimized.

lintool Oct 21, 2019

This comment has been minimized.

ianmilligan1 commented Oct 21, 2019 • edited

This comment has been minimized.

ianmilligan1 commented Oct 21, 2019

This comment has been minimized.

lintool commented Oct 21, 2019

This comment has been minimized.

ianmilligan1 commented Oct 21, 2019

This comment has been minimized.

lintool commented Oct 21, 2019

ruebot left a comment

This comment has been minimized.

ruebot Oct 21, 2019

This comment has been minimized.

ruebot Oct 21, 2019

This comment has been minimized.

lintool Oct 21, 2019

This comment has been minimized.

ruebot Oct 21, 2019

ianmilligan1 commented Oct 21, 2019 •

edited