Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactoring Documentation for Explanations and Consistent Structure #5

Merged
merged 19 commits into from Oct 21, 2019

Conversation

@ianmilligan1
Copy link
Member

ianmilligan1 commented Oct 21, 2019

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.

@lintool

This comment has been minimized.

Copy link
Member

lintool commented Oct 21, 2019

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

@@ -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

This comment has been minimized.

Copy link
@lintool

lintool Oct 21, 2019

Member

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

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

This comment has been minimized.

Copy link
@lintool

lintool Oct 21, 2019

Member

Highest-level heading should be "Text Analysis"?

@ianmilligan1

This comment has been minimized.

Copy link
Member Author

ianmilligan1 commented Oct 21, 2019

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

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

This comment has been minimized.

Copy link
Member Author

ianmilligan1 commented Oct 21, 2019

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

@lintool

This comment has been minimized.

Copy link
Member

lintool commented Oct 21, 2019

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

This comment has been minimized.

Copy link
Member Author

ianmilligan1 commented Oct 21, 2019

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

ianmilligan1 and others added 8 commits Oct 21, 2019
@lintool

This comment has been minimized.

Copy link
Member

lintool commented Oct 21, 2019

@ianmilligan1 changed structure as I suggested.

@ruebot
ruebot approved these changes Oct 21, 2019
Copy link
Member

ruebot left a comment

Just one question

README.md Outdated

Documentation from previous releases are also available:

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

This comment has been minimized.

Copy link
@ruebot

ruebot Oct 21, 2019

Member

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

This comment has been minimized.

Copy link
@ruebot

ruebot Oct 21, 2019

Member

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

This comment has been minimized.

Copy link
@lintool

lintool Oct 21, 2019

Member

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

This comment has been minimized.

Copy link
@ruebot
@ruebot ruebot merged commit 95a7559 into master Oct 21, 2019
@lintool lintool deleted the refactor-docs branch Oct 21, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants
You can’t perform that action at this time.