Git Product home page Git Product logo

atom-docs's People

Contributors

ablwr avatar anvit avatar aseles13 avatar corinnemrogers avatar corinnerogers avatar danloveg avatar djjuhasz avatar emescey avatar eviau-artefactual avatar fiver-watson avatar j4bbi avatar jennoit avatar jimadine avatar jraddaoui avatar kellyannewithane avatar kieranjol avatar mamedin avatar mbtj avatar mcantelon avatar melaniekung avatar rpearcemoses avatar sallain avatar samwilson avatar sbreker avatar scollazo avatar sevein avatar sromkey avatar testy-mctest avatar timhutch avatar tw4l avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

dan-gillean timhutch ahhn scdogan jhsimpson rozmi vonrosenchild samwilson noyerf rpearcemoses fiver-watson mesada lydiadean corinnerogers danloveg d-e-f-e-a-t jimadine dfloresbr kieranjol j4bbi eviau-artefactual nakamura196 kaiserzandrich jennoit testy-mctest jtgorman

atom-docs's Issues

Update full-width treeview docs for 2.6

Version of the documentation

2.6

Affected pages

Related Redmine issue tickets

Change summary

In issue #13135 we added a new setting for the full-width treeview that would display it collapsed on archival view pages, similar to the way the Advanced search panel is collapsed when first arriving on search/browse pages

Additionally, we have made the treeview pager setting configurable. Previously, this was hard-coded to 50 results - with the changes included in issue #13186, this value can now be modified by an administrator, supporting values between 10 (min) and 1,000 (max) treeview nodes per load.

Currently these new features are not included in the 2.5 or 2.6 documentation. This ticket will be associated with work to update the treeview documentation in the 2.6 documentation branch.

MySQL database creation command should better indicate format for including password

Version of the documentation

2.4; 2.5

Page (and section, if applicable) where the issue occurs

And same in 2.5. Keep in mind that in the 2.5 docs we will be removing the 14.04 instructions and replacing them with new 18.04 installation instructions.

Description of the issue

First mentioned by a user in the user forum, 2018-11-19.

When passing MySQL commands, there needs to be a space between the -u user parameter and the user name, but NO space between the -p password parameter and the actual password. Right now the docs don't include any password, and since many of our users are archivists unfamiliar with MySQL, we should be more explicit about the format requirements.

The user specifically mentioned the following:

mysql -h localhost -u root -p -e "CREATE DATABASE atom CHARACTER SET utf8 COLLATE utf8_unicode_ci;"

specifically "mysql -h localhost -u root -p -e" should be":

'mysql -h localhost -u root -pPASSWORD -e'

not

 'mysql -h localhost -u root -p PASSWORD -e'

Suggested fix

See above. Suggestion is to add a PASSWORD placeholder, and then explain in the text below the command that users should replace "PASSWORD" with the actual password they used during the installation and configuration of MySQL.

Clarify that absolute path is required for CLI SKOS imports

Documentation version affected: all (but add updates to 2.5 and 2.6)

Relevant documentation pages:

Issue encountered

An attempt to import a SKOS file with import:bulk task while using a relative path will produce an error with the message "Unable to parse data of an unknown format"

Example command:

php symfony import:bulk --taxonomy="35" --index skos/

Instead, a full absolute path needs to be provided:

php symfony import:bulk --taxonomy="35" --index /usr/share/nginx/atom/skos/

First discovered via a report in the User forum, 2020-02-28: link to Forum

Recommended change

Add a TIP or NOTE admonition in the documentation clarifying this.

Update instructions for ascending-descending sort feature - issue 12000

Version of the documentation
2.5

Link to Redmine ticket (if applicable)
https://projects.artefactual.com/issues/12000

Page (and section, if applicable) where the issue occurs
https://www.accesstomemory.org/en/docs/2.5/user-manual/access-content/browse/
https://www.accesstomemory.org/en/docs/2.5/user-manual/access-content/navigate/#sort-button

Description of the issue
a choice of ascending or descending sort has been added to browse results

Suggested fix

Add new docs for command-line physical storage container import task

Relevant documentation branch

  • 2.6

Affected pages

Issue description

In AtoM 2.6, a new command-line task has been added that supports the import of physical storage data using a CSV as input. New documentation will be required to cover this functionality.

Add client_max_body_size to PHP execution limits, and mention atom.conf PHP pool on this page

Documentation version

  • 2.5; 2.6

Relevant documentation pages

Relevant forum thread

Issue description

A user reported issues trying to upload a 72MB PDF. The issue was solved by adjusting the global php.ini execution limits, as well as adjusting the limits set in the atom.conf PHP pool (created during installation). However, to get it to work and resolve 413 Request Entity Too Large error, the user also had to adjust the atom.conf value for client_max_body_size.

Recommended solution

  1. Determine if this parameter is available in the global php.ini file. If yes, add mention of it to the Execution limits documentation page

  2. Remind users on the Execution limits page that limits are also set during installation in the atom.conf file, and to adjust those as well during tuning and configuration.

  3. Update the "Why can't I upload large digital objects" section of the Troubleshooting page with further information, including:

  • pointing to the atom.conf file
  • mentioning the 413 Request Entity Tool Large error and pointing to the client_max_body_size Nginx config variable as a possible solution
  • General review and updating based on FAQ forum posts on this topic

Path for enabling Debug mode in confg file incorrect

Version: 2.5

Place in docs: https://www.accesstomemory.org/docs/2.5/admin-manual/maintenance/debug/#using-qubit-dev-php

Issue noted

The path suggested for enabling Debug mode is currently listed as:

/etc/php/7.2/fpm/php-fpm.conf

This is incorrect - the above file contains general PHP configuration values, nothing specific to AtoM.

Recommended fix

The correct file and path in my Vagrant box is:

/etc/php/7.2/fpm/pool.d/atom.conf

This file has a header noting it is an ansible managed file (which we use to automate deployments and the vagrant box creation at Artefactual) so we should confirm with a developer that this is also correct for manually installed tarball AtoM instances as well.

Clarify changes to worker config when using PHP 7.0

NOTE: first reported via the user forum, 2019-10-02

Documentation version

2.5

Location in docs

Issue encountered

The docs suggest that the same configuration can be used for Ubuntu 16.04 and 18.04. However, with 16.04 we recommend using PHP 7.0. Note that in the [Service] section of the config block, the following line appears:

ExecStart=/usr/bin/php7.2 -d memory_limit=-1 -d error_reporting="E_ALL" symfony jobs:worker

This is specific to the PHP version. I believe for 16.04 it would need to be /usr/bin/php7.0, but we should confirm that.

Recommended change

We can either create separate blocks per version, or we can add a note highlighting this different, and pointing out that if you are using 7.0, you will need to change the line.

Add digital object to authority record

Version of the documentation
2.5

Link to Redmine ticket (if applicable)
https://projects.artefactual.com/issues/12650

Page (and section, if applicable) where the issue occurs
user-manual/import-export/upload-digital-object - direct to authority record for instructions but add distinctions/limitations for authority record DOs
user-manual/add-edit-content/authority-records/ - describe how to add digital objects
https://www.accesstomemory.org/en/docs/2.5/user-manual/access-content/search-atom/#authicon-authority-records - describe/update search functionality for authority records

Description of the issue
This new feature for authority records will allow an authenticated (i.e. logged in) user with sufficient permissions to attach a single digital object to an authority record. Search results will also show attached digital objects and first few lines of the related actor's history.

Suggested fix

Clarify that qubitParentSlug column in Accessions CSV will not accept piped values

Documentation version

All! (but updates should be made in 2.5)

Location in the documentation

Issue and recommended fix

At some points it says things like "Alternatively, you can use the qubitParentSlug column to link existing descriptions ..." and later, "To link incoming accession records to existing archival descriptions, you can add a column named qubitParentSlug" (bolding mine, to point out pluralization).

We should clarify this, and add a note admonition stating that only one slug can be linked at a time via CSV import.

Add browse hierarchy documentation, refs #11955

Version of the documentation
2.5

Link to Redmine ticket (if applicable)
https://projects.artefactual.com/issues/11955

Page (and section, if applicable) where the issue occurs
Browse page: https://www.accesstomemory.org/en/docs/2.5/user-manual/access-content/browse/#desc-browse-archival-descriptions

Settings page: https://www.accesstomemory.org/en/docs/2.5/user-manual/administer/settings/#treeview-settings

Description of the issue
New feature - addition of ability to browse by treeview hierarchy

Suggested fix

Links to ISAAR-CPF standard in Authority records page are broken

Version of the documentation

2.4 and 2.5

Link to Redmine ticket (if applicable)

N/A

Page (and section, if applicable) where the issue occurs

https://www.accesstomemory.org/en/docs/2.4/user-manual/add-edit-content/authority-records/#add-a-new-authority-record-from-the-main-menu

https://www.accesstomemory.org/en/docs/2.4/user-manual/add-edit-content/authority-records/#add-a-new-authority-record-from-an-authority-record-view-page

Description of the issue

I noticed that the links to the ISAAR-CPF standard on the ICA's website are broken, because the ICA has moved the standard without adding a redirect. The correct link location is now:

Suggested fix

Updating the current links to the new link provided above

Clipboard documentation is missing Save settings and mention of load merging options

Version of the documentation

2.5

Link to Redmine ticket (if applicable)

https://projects.artefactual.com/issues/11360

Page (and section, if applicable) where the issue occurs

Description of the issue

Issue #78 addressed the initial documentation of the new Clipboard save option introduced in the AtoM 2.5 release. However, a couple things are missing that should be added:

  • The global setting for number of days to store a saved clipboard is not documented. Since this setting's default value is 0 days, we need to document it, and add an IMPORTANT admonition to the user manual to ensure that admins configure this value before proceeding.
  • The current clipboard save documentation doesn't mention the two different options for loading a clipboard (merge vs overwrite)

Suggested fix

  • Add new subsection to Administer / Settings / Global settings for the clipboard save setting.
  • Add IMPORTANT admonition to the clipboard save end user docs mentioning the setting
  • Add a note to the release documentation on the wiki about this setting
  • Add more info about loading clipboards and the various options

Delete digital object from command line

Version of the documentation

New content to add to 2.4, 2.5

Page (and section, if applicable) where the issue occurs

Description of the issue

Digital objects can be deleted from the command line

Suggested fix

Delete a digital object

You can do this if you have the slug of the related description. The basic syntax of the command is:

php symfony digitalobject:delete slug-of-description

Where slug-of-description represents the target record.

Deleting digital objects from a complex hierarchy

The task also has one option, that can be used to delete all digital objects in a hierarchy. You can do this using the CLI task: digitalobject:delete

So you would find the slug for the top level description for which you wanted to remove the digital objects (and for its descendants), and then you could run:

php symfony digitalobject:delete --and-descendants your-top-level-description-slug

Where your-top-level-description-slug represents the slug of the parent record.

NOTE: this task will not update the search index, so you need to run search:populate afterwards.

Remove mention(s?) of Transifex from documentation

Documentation version

2.5

Location in docs

Issue encountered and recommended fix

  • Transifex is mentioned by name
  • We should remove these
  • Instead, we should keep the reference general and not mention a specific platform where possible. Where one is needed, update to Weblate.

Update instructions for restarting php-fpm (remove 14.04, add 18.04)

Version of the documentation
2.5

Link to Redmine ticket (if applicable)
12609 (release process)

Pages (and section, if applicable) where the issue occurs
https://www.accesstomemory.org/en/docs/2.5/admin-manual/maintenance/troubleshooting/#troubleshooting-restart-php-fpm

https://www.accesstomemory.org/en/docs/2.5/admin-manual/installation/upgrading/

https://www.accesstomemory.org/en/docs/2.5/admin-manual/installation/execution-limits/

https://www.accesstomemory.org/en/docs/2.5/admin-manual/installation/linux/ubuntu-trusty/ - remove this page from the 2.5 documentation

https://www.accesstomemory.org/en/docs/2.5/admin-manual/ (auto)

https://www.accesstomemory.org/en/docs/2.5/contents/ (auto)

Description of the issue
remove references to restarting php-fpm for Ubuntu 14.04 and add instructions for 18.04

Update Docker compose installation instructions for 2.5 and ES 5 memory requirements

Version of the documentation

2.5 - https://www.accesstomemory.org/docs/2.5/dev-manual/env/compose/

Related user forum thread:

Page (and section, if applicable) where the issue occurs

https://www.accesstomemory.org/en/docs/2.5/dev-manual/env/compose/#spin-it-up

Description of the issue

2 things. First, the documentation has not been updated to point at the 2.5 branch. Second, in 2.5, we have replaced Elasticsearch 1.7 with version 5.5. A user in the forum recently reported needing to increase the max virtual memory areas to get ES properly installed and configured, so we may want to include a note about this as well. See the related forum post, linked above.

Suggested fix

1. Correct atom source version
replace:

git clone -b stable/2.4.x https://github.com/artefactual/atom.git atom

with:

git clone  --depth 1 -b qa/2.5.x https://github.com/artefactual/atom.git atom

2. Add a note about the vm memory requirement before running docker-compose

Suggestion from Ricardo in the forum
:
Note: For the Elasticsearch container to run properly, you may need to increase the max virtual memory areas vm.max_map_count to at least [262144]. To do so:

sudo sysctl -w vm.max_map_count=262144

The suggestion is to add this right before the following in our current docs:

# Create and start containers. This may take a while the first time you run
# it because all the images have to be downloaded (e.g. percona, memcached)
# and the AtoM image has to be built.
docker-compose up -d

Update create authority records to add subject and place access points

Version of the documentation
2.5

Link to Redmine ticket (if applicable)
https://projects.artefactual.com/issues/12647

Page (and section, if applicable) where the issue occurs
https://www.accesstomemory.org/en/docs/2.5/user-manual/add-edit-content/authority-records/#add-access-points-to-your-authority-record

Description of the issue
New feature: an authorized user can now add subject and place access points to authority records - document this process with screenshots; also the current limitations of this feature

Suggested fix

Update docs to describe DO load task ability to discard master DO after derivative creation

Version of the documentation
2.5

Link to Redmine ticket (if applicable)
https://projects.artefactual.com/issues/12840

Page (and section, if applicable) where the issue occurs
Update Load digital objects via the command-linesection in https://www.accesstomemory.org/en/docs/2.5/admin-manual/maintenance/cli-import-export/#digital-object-load-task

Description of the issue
Documentation should discuss new import option to prevent copying "master" digital object from source to "uploads".

Suggested fix
Add description of use case for --link-source option.
Add description for the --limit option.

Test CSV accession imports and updates and update documentation

Version of the documentation

New content for 2.4, 2.5

Link to User Forum question

Related user forum thread:

Page (and section, if applicable) where the issue occurs

Description of the issue

Currently docs don't note anything about being able to update accessions via CSV import

Suggested fix

It seems like maybe matches on accession number will currently import and update, rather than throwing an error or skipping, etc. Do some testing, and add notes to the docs.

Add markdown documentation, refs #12148

Version of the documentation

2.5

Link to Redmine ticket (if applicable)

https://projects.artefactual.com/issues/12148

Page (and section, if applicable) where the issue occurs

Primary page affected: https://www.accesstomemory.org/docs/2.5/user-manual/add-edit-content/formatting/

Description of the issue

In 2.5 we have added support for Markdown via Parsedown, a PHP library. We need to add documentation for this, and remove the old documentation for the custom linking syntax.

Suggested fix

Add new documentation.

Missing terminal session entry in docker-compose docs

Version of the documentation

2.4, 2.5

Page (and section, if applicable) where the issue occurs

  • Underneath the connect to AtoM anchode here

Description of the issue

The final line of the docs reads as follows:

In case you have any doubts, we’ve prepared a recording of the terminal session:

But there is no terminal session!

Suggested fix

See if we can find a link if there is one, or remove the prompt.

Fix typo in documentation under Authority Records

Version of documentation: 2.5
Section: Authority Records
Link: https://www.accesstomemory.org/en/docs/2.5/user-manual/add-edit-content/authority-records/#authority-records

Location: 1st paragraph
Sentence with error: "Typically, authority records contain information about the authorized form of name and other forms of name by which the actor is known, dates of existence, relevant adminstrtive or biographical history details, and other contextual information; additionally, roles in events and relationships with archival materials are also captured and expressed."

Error: "adminstrtive"
Suggested fix: "administrative"

Update GDPR privacy notice documentation

Version of the documentation

2.5

Link to Redmine ticket (if applicable)

https://projects.artefactual.com/issues/12500

Page (and section, if applicable) where the issue occurs

https://www.accesstomemory.org/docs/2.5/user-manual/administer/settings/

Description of the issue

Basic instructions were added to the 2.4 branch for the 2.4.1 release, but they were focused on the unique upgrade steps necessary for 2.4.1. These were not copied over to the 2.5 documentaiton.

Suggested fix

Add new documentation for 2.5

Update references to 2.4

Version of the documentation
2.5

Link to Redmine ticket (if applicable)

Page (and section, if applicable) where the issue occurs

https://www.accesstomemory.org/en/docs/2.5/dev-manual/env/compose/ “qa/2.5.x” to “qa/2.6.x” and “stable/2.4” to “stable/2.5"

https://www.accesstomemory.org/en/docs/2.5/admin-manual/installation/linux/ubuntu-xenial/ mentions of 2.4 in “Download AtoM”

https://www.accesstomemory.org/en/docs/2.5/admin-manual/installation/linux/ubuntu-trusty/ same

Description of the issue

Suggested fix

Update hierarchy browser documentation to include settings

Documentation version

2.5

Related issue

Relevant documentation sections

Description of the issue

Initial documentation for the hierarchy browser was added in #76 and related PR #77

However, mention of the setting to enable/disable this feature was not included. Additionally, there's no sub-section anchor link to point directly to the hierarchy browser section in the browse docs.

Suggested fix

  • Add bierarchy browse settings docs to User manual > Administration > Settings > Treeview
  • Review User manual > Browse > Browse archival descriptions and see if a subheading can be added

Add docs for search:status task

Version of the documentation

2.5

Link to Redmine ticket (if applicable)

Page (and section, if applicable) where the issue occurs

Description of the issue and suggested fix

Add docs for new task, and add mention of new task wherever it would be useful

PHP-FPM restart instructions on Debug page should be version-specific

Version of the documentation

2.4, 2.5

Location: Manual, Page (and section, if applicable) where the issue occurs

Description of the issue

Debug mode page tells users to restart PHP-FPM, but only includes instructions for doing so for PHP5.

Suggested fix

Update restart instructions to include specific instructions for 14.04 and 16.04. E.g.:

**Ubuntu 14.04:**

.. code-block::bash
   
   sudo service php5-fpm restart

**Ubuntu 16.04:**

.. code-block:: bash
   
   sudo systemctl restart php7.0-fpm

Improve SQL query documentation and move to a dedicated page

We frequently share SQL queries in the user forum to help users troubleshoot problems, or else accomplish tasks that are not accommodated by existing user interface functionality or command-line tasks.

We've long had a section in the documentation called "Common AtoM database queries" but it is very limited, and I frequently have to repeat in the forum how to even access the MySQL command prompt. Meanwhile, I have collected many more useful queries from years of client and forum support, and would like to capture some of these, where they might be useful to the broader AtoM community.

This issue ticket will move the current "Common AtoM database queries" section out of the CLI tools page and into its own page in the Administrator's manual. It will also expand on the current content.

Relevant documentation branch: 2.6

Affected documentation pages:

Add docs for permissive slug generation option

Version of the documentation

2.5

Link to Redmine ticket (if applicable)

https://projects.artefactual.com/issues/11761

Page (and section, if applicable) where the issue occurs

Suggested fix

Add new docs and update sections that currently mention how slugs are formed in AtoM

Add audit log documentation

Version of the documentation

2.5

Link to Redmine ticket (if applicable)

https://projects.artefactual.com/issues/12130

Page (and section, if applicable) where the issue occurs

Settings
Archival descriptions
Description updates
Users

Description of the issue

New functionality for audit logging added in 2.5. Need to document

Suggested fix

Add new docs

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.